Guía de Inicio Rápido

Esta guía te ayudará a comenzar rápidamente con nuestra API para crear una compañía, configurar sus credenciales tributarias y logo, y finalmente enviar una factura o boleta.

Paso 1: Crear la Compañía

Para empezar, lo primero que debes hacer es crear una compañía utilizando nuestra API. A continuación, se muestra un ejemplo de cómo hacerlo:

Ejemplo de Solicitud

POST /api/company HTTP/1.1
Host: invoice.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

{
    "tax_id": "123456789101",
    "business_name": "Tu Empresa S.A.C.",
    "trade_name": "Tu Empresa S.A.C",
    "phone": "+51 986187825",
    "email": "email@dominio.com",
    "country": "PE",
    "address": {
        "postal_zone": "150122",
        "country": "PE",
        "country_subentity": "LIMA", //Departamento
        "city": "LIMA", //Provincia
        "district": "MIRAFLORES", //Distrito
        "city_subdivision": "MIRAFLORES", //Urbanización-Comuna
        "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302 COM. SAN MIGUEL DE MIRAFLORES"
    },
    "web_hook":"https://www.dominio.com/webhook/" //Puede agregar un webhook por empresa, caso contrario se tomará en cuenta el webhook de la cuenta.
}

Ejemplo de Respuesta

{
    "id": "com_b2ad4cfce3be408fb100062b06f8dc0b",
    "business_name": "Tu Empresa S.A.C.",
    "trade_name": "Tu Empresa S.A.C",
    "tax_id": "123456789101",
    "country": "PE",
    "phone": "+51 986187825",
    "email": "email@dominio.com",
    "address": {
        "postal_zone": "15074",
        "country": "PE",
        "country_subentity": "LIMA",
        "city": "LIMA",
        "district": "MIRAFLORES",
        "city_subdivision": "MIRAFLORES", 
        "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302 COM. SAN MIGUEL DE MIRAFLORES",
        "type_code": null
    },
    "metadata": null,
    "logo": null,
    "web_hook": "https://www.dominio.com/webhook/"
}

Paso 2: Configurar Credenciales Tributarias y Logo

Una vez creada la compañía, el siguiente paso es configurar sus credenciales tributarias y logo. Para esto, utilizamos un formulario multipart form-data para subir los archivos necesarios.

Conversión de Certificados (.p12/.pfx a .cer y .key)

Para convertir un certificado en formato .p12 o .pfx a un archivo .cer y un archivo .key, puedes utilizar la herramienta OpenSSL. A continuación, se detallan los pasos necesarios:

Requisitos Previos

OpenSSL: Asegúrate de tener OpenSSL instalado en tu sistema. Puedes descargarlo e instalarlo desde OpenSSL.
Es posible que se te pida ingresar la contraseña del archivo .p12 o .pfx durante el proceso de conversión.

Pasos para la Conversión

# Convertir .p12/.pfx a .pem
openssl pkcs12 -in tu_certificado.p12 -out archivo_intermedio.pem -nodes

# Extraer el certificado .cer
openssl x509 -in archivo_intermedio.pem -out tu_certificado.cer

# Extraer la clave privada .key
openssl pkey -in archivo_intermedio.pem -out tu_certificado.key

Ejemplo de Solicitud

POST /api/company/setup
Host: invoice.tandia.io
Authorization: Bearer token-de-api

Body form-data
| Campo            | Descripción                      |
|------------------|----------------------------------|
| `tax_id`         | 11606335125                      |
| `cert_file`      | tu_certificado.cer               |
| `key_file`       | tu_certificado.key               |
| `tax_user`       | usuario_secundario_sunat         |
| `tax_password`   | password_usuario_secundario_sunat|
| `logo`           | tu_logo.png                      |
| `country_code`   | PE                               |

Ejemplo de Respuesta

{
    "id": "com_b2ad4cfce3be408fb100062b06f8dc0b",
    "business_name": "Tu Empresa S.A.C.",
    "trade_name": "Tu Empresa S.A.C",
    "tax_id": "123456789101",
    "country": "PE",
    "phone": "+51 986187825",
    "email": "email@dominio.com",
    "address": {
        "postal_zone": "15074",
        "country": "PE",
        "country_subentity": "LIMA", 
        "city": "LIMA", 
        "district": "MIRAFLORES", 
        "city_subdivision": "MIRAFLORES", 
        "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302 COM. SAN MIGUEL DE MIRAFLORES",
        "type_code": null
    },
    "metadata": null,
    "logo": null,
    "web_hook": "https://www.dominio.com/webhook/"
}

Paso 3: Enviar una Factura o Boleta

Con la compañía configurada, ya puedes proceder a enviar una factura o boleta.

Ejemplo de Solicitud

POST /api/invoice
Host: invoice.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

{
  "number": "FF10-00000029",
  "date": "2023-11-01T18:46:00-05:00",
  "external_id": 12345566, // Puedes enviar tu ID aquí para identificar tu registro en la base de datos.
  "customer": {
    "document_type": "6",
    "document_number": "20740021552",
    "registration_name": "Jane Doe SAC",
    "email": "jdoe@business.com"
  },
  "company": {
    "tax_id": "ruc-registrada-en-api"
  },
  "currency": "PEN",
  "payment_method": "cash",
  "tax_total": 36.00,
  "sale_value": 200.00,
  "subtotal": 236.00,
  "total": 236.00,
  "taxed_amount": 200.00,
  "tax_amounts": [
    {
      "code": "IGV",
      "amount": 36.00
    }
  ],
  "items": [
    {
      "free": false,
      "code": "P001",
      "unit": "NIU",
      "description": "PRODUCTO 1",
      "quantity": 2.00,
      "unit_value": 100.00,
      "unit_price": 118.00,
      "tax_total": 36.00,
      "sale_value": 200.00,
      "subtotal": 200.00,
      "taxes": [
        {
          "code": "IGV",
          "amount": 36.00
        }
      ],
      "total": 236.00
    }
  ]
}

Ejemplo de Respuesta

{
  "id": "doc_b2bb89fd51404504830ce194f3754a8e",
  "type": "receipt",
  "number": "FF10-00000029",
  "date": "2023-11-01T18:46:00-05:00",
  "customer": {
    "document_type": "6",
    "document_number": "20740021552",
    "registration_name": "Jane Doe SAC",
    "email": "jdoe@business.com"
  },
  "company": {
    "tax_id": "ruc-registrada-en-api"
  },
  "currency": "PEN",
  "payment_method": "cash",
  "tax_total": 36.00,
  "sale_value": 200.00,
  "subtotal": 236.00,
  "total": 236.00,
  "taxed_amount": 200.00,
  "tax_amounts": [
    {
      "code": "IGV",
      "amount": 36.00
    }
  ],
  "items": [
    {
      "free": false,
      "code": "P001",
      "unit": "NIU",
      "description": "PRODUCTO 1",
      "quantity": 2.00,
      "unit_value": 100.00,
      "unit_price": 118.00,
      "tax_total": 36.00,
      "sale_value": 200.00,
      "subtotal": 200.00,
      "taxes": [
        {
          "code": "IGV",
          "amount": 36.00
        }
      ],
      "total": 236.00
    }
  ],
  "status": "created",
}

Estados del Documento

A lo largo de su ciclo de vida, un documento puede pasar por los siguientes estados:

created: El documento ha sido enviado por primera vez.
pending: El documento está a la espera de ser procesado.

Resultados del Proceso

Después del procesamiento, el documento puede tener uno de los siguientes estados:

succeeded: El documento ha sido aceptado por la entidad fiscal.
error: La entidad fiscal rechazó el documento por algún error.
failed: No se pudo entregar el documento a la entidad fiscal debido a que el servicio de la entidad fiscal está fuera de línea o caído.

Nota Importante:

En los casos de failed, nuestro sistema se encarga de reintentar cuantas veces sea necesario para obtener una respuesta de la entidad fiscal.

Cabe señalar que en el webhook solo se notifican los estados succeeded o error.

Conclusión

Siguiendo estos pasos, podrás crear y configurar una compañía, y enviar facturas o boletas usando nuestra API. Si tienes alguna pregunta o necesitas asistencia, no dude en contactar a nuestro equipo de soporte.