La Facturación de Toku permite emitir y gestionar CFDIs en México de forma automática, a partir de tus pagos y/o deudas, cumpliendo con la normativa fiscal del SAT y sin procesos manuales. Desde un mismo lugar emites facturas (PUE y PPD), complementos de pago, cancelaciones y notas de crédito.

Cómo funciona: el modelo en dos capas

La integración se entiende en dos capas. Primero cargas la información fiscal (Data In) del receptor y de la deuda; después emites el CFDI y recibes el documento timbrado.

Glosario

1. Antes de empezar

1.1 Autenticación

Todas las llamadas se autentican con tu API Key en el header x-api-key, contra la base URL https://api.trytoku.com.

Por ejemplo:

curl https://api.trytoku.com/customer-billing-data \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json"

1.2 Requisitos fiscales

La facturación se apoya en tu propia infraestructura fiscal. Antes de la primera emisión necesitas:

• Estar registrado en el SAT con un RFC válido.
• Contar con tu Certificado de Sello Digital (CSD): archivos .cer, .key y contraseña.
• Tener contratado Facturama (el PAC con el que timbra Toku) y contar con folios (timbres) disponibles.
• Configurar estas credenciales junto con el equipo de Toku. Es un setup único; mientras no esté listo, la funcionalidad no se activa.

1.3 Requisitos previos

La facturación se construye sobre los objetos core de Toku. Antes de facturar, según el caso, deben existir:

• El Customer (cus_...) — siempre.
• La Invoice (in_...) — siempre.
• La Transaction (trs_...) — para PUE y para complementos de pago.

1.4 ¿Qué tipo de CFDI corresponde?

La pregunta clave es en qué momento facturas. Esto define el tipo de CFDI y a qué objeto se ancla la emisión.

2. Cargar la información fiscal (Data In)

Antes de emitir cualquier CFDI necesitas cargar los datos fiscales del receptor y de la deuda.

2.1 Información fiscal del Customer (receptor)

Guarda los datos fiscales con los que se emitirán las facturas del Customer.

Crear — POST /customer-billing-data

Request

Por ejemplo

{
  "id_customer": "cus_example1234",
  "tax_id": "XAXX010101000",
  "tax_regime": "601",
  "legal_name": "Empresa Demo SA de CV",
  "tax_zip_code": "54054",
  "billing_address": "Emerson 180, CDMX",
  "billing_email": "[email protected]"
}

Consultar — GET /customer-billing-data/{id_customer}

Devuelve la información fiscal cargada para ese Customer. Usa el id_customer como path param.

Actualizar — PATCH /customer-billing-data/{id_customer}

Mismos campos que en la creación (todos opcionales en el body; envías solo los que cambian). Úsalo, por ejemplo, para corregir un régimen o una razón social que no coincide con el SAT.

2.2 Información fiscal de la Deuda (invoice)

Define cómo se construye el CFDI de esa deuda: uso, tipo de pago, conceptos e impuestos.

Crear — POST /invoice-billing-data

Campos de item

Campos de cada taxes[]

Request

Por ejemplo

{
  "id_invoice": "in_example1234",
  "cfdi_use": "G03",
  "cfdi_payment_method": "PPD",
  "item": {
    "product_code": "81112101",
    "product_description": "Servicio mensual",
    "unit_code": "E48",
    "quantity": 1,
    "tax_object": "02",
    "unit_price": 200.45,
    "taxes": [
      {
        "rate": 0.16,
        "is_retention": false,
        "name": "IVA"
      }
    ]
  },
  "observations": "Observaciones opcionales"
}

Consultar — GET /invoice-billing-data/{id_invoice}

Devuelve la información fiscal cargada para esa Invoice.

Actualizar — PUT /invoice-billing-data/{id_invoice}

Requiere cfdi_use, cfdi_payment_method e item en el body.

2.3 Facturación a público general

Cuando no cuentas con los datos fiscales del Customer pero igual quieres avanzar con la factura, puedes cargar información fiscal genérica (público general) para uno o varios customers a la vez.

Crear — POST /customer-billing-data/general-public/bulk

Request

{
  "id_customers": [
    "cus_K38NHOpo35qLUDgFUecLbhADCHX-Tvvn",
    "cus_sB7M0mKTUllsc_ec2Tp09fGBVzvH5jMR"
  ]
}

Response

{
  "created": ["cus_K38NHOpo35qLUDgFUecLbhADCHX-Tvvn"],
  "skipped": [
    { "id_customer": "cus_sB7M0mKTUllsc_ec2Tp09fGBVzvH5jMR", "reason": "Customer already has billing data" }
  ],
  "failed": [],
  "summary": { "total_requested": 2, "created_count": 1, "skipped_count": 1, "failed_count": 0 }
}

3. Emitir el CFDI

Con la información fiscal cargada, disparas la emisión. Todas las respuestas devuelven uno o más objetos billing_document.

3.1 Factura PUE: POST /billing-documents/pue

Emite una factura de pago en una sola exhibición, asociada a una transaction (el pago ya ocurrió).

Request

{
  "id_transaction": "trs_jasdkjasndi",
  "id_account": "acc_2BrF6x",
  "issue_date": "2025-10-02T10:25:00"
}

3.2 Factura PPD: POST /billing-documents/ppd

Emite una factura de pago en parcialidades o diferido, asociada a la deuda (invoice). El pago se registra después con un complemento.

Request

{
  "id_invoice": "in_MxSCCZLVndll",
  "id_account": "acc_2BrF6x"
}

Response (ejemplo, aplica a PUE y PPD)

[
  {
    "id_billing_document": "bd_JdDo6bebL",
    "id_invoice": "in_MxSCCZLVndll",
    "id_transaction": null,
    "id_account": "acc_2BrF6x",
    "id_customer": "cus_3pVgIaKg",
    "status": "ISSUED",
    "type": "INVOICE",
    "folio": "15",
    "issue_date": "2025-10-02T10:25:00",
    "sub_total": 100.5,
    "discount": 0.0,
    "total": 116.58,
    "pdf_url": "https://storage.cloud.google.com/.../15.pdf",
    "xml_url": "https://storage.cloud.google.com/.../15.xml",
    "provider_external_id": "qgzRhubiJ",
    "fiscal_billing_id": "a38685b0-99f8-4fb6-9",
    "tax_id": "BOOE980",
    "tax_regime": "605",
    "tax_zip_code": "54054"
  }
]

3.3 Complemento de pago: POST /billing-documents/ppd-complement

Emite el complemento que registra el pago de una factura PPD previamente emitida.

El objeto billing_document

Es lo que devuelven la emisión, la consulta y los webhooks. Campos principales:

4. Recibir notificaciones (webhooks)

Toku notifica la emisión de documentos vía webhook. Inscribe un Webhook Endpoint suscrito al evento de facturación y valida la firma Toku-Signature igual que con el resto de eventos (ver la guía de Notificaciones y webhooks).

Evento billing_document.created

Notifica cuando un documento fiscal ha sido creado. El payload trae el mismo objeto billing_document, incluyendo los enlaces a PDF y XML.

{
  "id": "wheve_72s5JQEfl3zJf9rkjhvkhjvhclu",
  "event_type": "billing_document.created",
  "id_billing_document": "bd_ljhvcgkgv",
  "id_invoice": "in_JgPlqLz6Whpr",
  "id_transaction": "trs_sMfOXfkoXTyoTK",
  "id_customer": "cus_KfRGfQFVO",
  "status": "ISSUED",
  "type": "INVOICE",
  "folio": "5",
  "issue_date": "2025-10-01T01:06:47",
  "sub_total": 8.62,
  "discount": 0.0,
  "total": 10.0,
  "pdf_url": "https://storage.cloud.google.com/.../doc.pdf",
  "xml_url": "https://storage.cloud.google.com/.../doc.xml",
  "provider_external_id": "GpEdu_HCzvtldgVDW8aUwg2",
  "fiscal_billing_id": "example_uuid",
  "related_fiscal_billing_id": null,
  "tax_id": "EXAMPLERFC",
  "tax_regime": "611",
  "tax_zip_code": "27345"
}

5. Operar sobre facturas emitidas

5.1 Cancelación — POST /billing-documents/{id_billing_document}/cancel

Solicita la cancelación de una factura ante el SAT. Usa el id_billing_document como path param (sin body).

Response

{
  "success": true,
  "message": "Billing document {id} cancelled",
  "data": {
    "Status": "canceled",
    "Message": "Cancelado: Cancelado sin aceptación",
    "IsCancelable": "Cancelable sin aceptación",
    "Uuid": "uuid",
    "RequestDate": "2025-10-23T12:55:00",
    "AcuseStatus": 201,
    "AcuseStatusDetails": "Solicitud de cancelación recibida."
  }
}

5.2 Nota de crédito — POST /billing-documents/credit-note

Corrige o revierte (total o parcialmente) una factura ya emitida. Queda vinculada a la factura origen.

Request

{
  "provider_external_id": "GpEdu_HCzvtldgVDW8aUwg2",
  "payment_form": "03",
  "reason": "Devolución parcial",
  "amount": 100,
  "items": [
    {
      "product_code": "81112101",
      "product_description": "Servicio mensual",
      "unit_code": "E48",
      "quantity": 1,
      "unit_price": 100,
      "tax_object": "02",
      "taxes": [
        { "rate": 0.16, "is_retention": false, "name": "IVA" }
      ]
    }
  ]
}

6. Consultar facturas — GET /billing-documents

Devuelve los documentos fiscales emitidos, con filtros y paginación.

7. Buenas prácticas y errores frecuentes

No todos los errores de facturación requieren una acción sobre la integración: muchos vienen de los datos fiscales que cargas o de definiciones del propio negocio. La clave es identificar el origen.

Datos fiscales del customer

Datos de la deuda / invoice

Cancelaciones y notas de crédito

Recomendaciones generales

• No dispares dos veces la misma emisión; usa la consulta para verificar si ya existe el documento antes de reintentar.
• Guarda id_billing_document, fiscal_billing_id y provider_external_id: los necesitarás para cancelar, emitir complementos y notas de crédito.
• Una cancelación pendiente o rechazada no se reintenta.

8. Referencia rápida de endpoints