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.

Antes de empezar

Para emitir un comprobante necesitas tres piezas:

Un token válido en el encabezado Authorization, normalmente el api_key entregado para la cuenta. Ver Autenticación para el detalle de credenciales.
Una compañía registrada con su tax_id y datos fiscales.
Una serie o número de comprobante. Si envías number, usas numeración propia; si usas un endpoint básico con serie, Tandia toma el correlativo configurado para esa serie.

En los endpoints detallados debes enviar los totales e impuestos calculados. En los endpoints básicos, como /api/document/basic/invoice, puedes enviar datos simples de producto y la API calcula los importes.

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.test.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

{
    "tax_id": "12345678910",
    "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": "COM. SAN MIGUEL DE MIRAFLORES", //Urbanización-Comuna
        "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302"
    },
    "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": "12345678910",
  "country": "PE",
  "phone": "+51 986187825",
  "email": "email@dominio.com",
  "address": {
    "postal_zone": "15074",
    "country": "PE",
    "country_subentity": "LIMA",
    "city": "LIMA",
    "district": "MIRAFLORES",
    "city_subdivision": "COM. SAN MIGUEL DE MIRAFLORES",
    "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302",
    "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, certificado digital y logo.

El detalle completo de configuración de certificado digital (formatos soportados, POST /api/company/init para .p12/.pfx, POST /api/company/setup para .cer/.key, usuario secundario SUNAT y credenciales de guías) está centralizado en Compañía: Configuración de certificado digital.

A continuación se muestra solo el flujo básico con certificado separado para completar esta guía.

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

Si cuentas con un certificado en formato .p12 o .pfx, conviértelo a .cer y .key usando OpenSSL:

openssl pkcs12 -in tu_certificado.p12 -out archivo_intermedio.pem -nodes
openssl x509 -in archivo_intermedio.pem -out tu_certificado.cer
openssl pkey -in archivo_intermedio.pem -out tu_certificado.key

Ejemplo de Solicitud

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

Body form-data
| Campo            | Descripción                       |
|------------------|-----------------------------------|
| `tax_id`         | 12345678910                       |
| `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": "12345678910",
  "country": "PE",
  "phone": "+51 986187825",
  "email": "email@dominio.com",
  "address": {
    "postal_zone": "15074",
    "country": "PE",
    "country_subentity": "LIMA",
    "city": "LIMA",
    "district": "MIRAFLORES",
    "city_subdivision": "COM. SAN MIGUEL DE MIRAFLORES",
    "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302",
    "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.test.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-registrado-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": "invoice",
  "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-registrado-en-api"
  },
  "currency": "PEN",
  "payment_method": "cash",
  "tax_total": 36.0,
  "sale_value": 200.0,
  "subtotal": 236.0,
  "total": 236.0,
  "taxed_amount": 200.0,
  "tax_amounts": [
    {
      "code": "IGV",
      "amount": 36.0
    }
  ],
  "items": [
    {
      "free": false,
      "code": "P001",
      "unit": "NIU",
      "description": "PRODUCTO 1",
      "quantity": 2.0,
      "unit_value": 100.0,
      "unit_price": 118.0,
      "tax_total": 36.0,
      "sale_value": 200.0,
      "subtotal": 200.0,
      "taxes": [
        {
          "code": "IGV",
          "amount": 36.0
        }
      ],
      "total": 236.0
    }
  ],
  "status": "created"
}

Estados del Documento

A lo largo de su ciclo de vida, un documento puede pasar por los siguientes estados. Estos estados también se usan en las consultas por documento y en las notificaciones por webhook:

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 o el comprobante contiene un error no reprocesable.
failed: No se pudo entregar el documento a la entidad fiscal por un fallo técnico temporal.

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.