Create Invoice (Full) - Timbre by Taxo

curl -X POST https://api.usatimbre.com/api/timbre/create-invoice-full \
  -H "Authorization: Bearer tmb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_info": {
      "tax_id": "XAXX010101000",
      "cfdi_use": "G03",
      "taxpayer": "Juan Pérez García",
      "postal_code": "06600",
      "fiscal_regimen": "612"
    },
    "receipt_image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "success": true,
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "status": "processing",
      "amount": null,
      "currency": "MXN",
      "vendor": null,
      "member_rfc": "XAXX010101000",
      "created_at": "2024-01-21T10:30:00Z",
      "pdf_url": null,
      "xml_url": null
    },
    "member": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "phone_number": "+525512345678",
      "tax_id": "XAXX010101000",
      "org_id": "org_123456",
      "created_at": "2024-01-21T10:00:00Z"
    },
    "created_profile": true,
    "credits_remaining": 9
  }
}

POST

api

timbre

create-invoice-full

curl -X POST https://api.usatimbre.com/api/timbre/create-invoice-full \
  -H "Authorization: Bearer tmb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_info": {
      "tax_id": "XAXX010101000",
      "cfdi_use": "G03",
      "taxpayer": "Juan Pérez García",
      "postal_code": "06600",
      "fiscal_regimen": "612"
    },
    "receipt_image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "success": true,
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "status": "processing",
      "amount": null,
      "currency": "MXN",
      "vendor": null,
      "member_rfc": "XAXX010101000",
      "created_at": "2024-01-21T10:30:00Z",
      "pdf_url": null,
      "xml_url": null
    },
    "member": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "phone_number": "+525512345678",
      "tax_id": "XAXX010101000",
      "org_id": "org_123456",
      "created_at": "2024-01-21T10:00:00Z"
    },
    "created_profile": true,
    "credits_remaining": 9
  }
}

Overview

Create an invoice from a receipt image in a single call. Provide complete tax info to use an existing member by RFC or automatically create a new member profile. Supports JSON (with base64 image) or multipart/form-data (with file upload).

This operation requires 1 credit. Credits are consumed from the API key owner, not the member profile.

Authentication

Requires a valid API key with:

API key owner belongs to an organization
api_keys_enabled feature flag enabled for the organization

Request Body

tax_info

object

required

Tax information object

Show tax_info properties

tax_id

string

required

RFC (Registro Federal de Contribuyentes, 12-13 characters). Example: XAXX010101000

cfdi_use

string

required

CFDI usage code. Common values:

G01 - Adquisición de mercancías
G02 - Devoluciones, descuentos o bonificaciones
G03 - Gastos en general
S01 - Sin efectos fiscales

fiscal_regimen

string

required

Tax regime code (e.g., 601, 612, 626).

taxpayer

string

required

Full name or business name.

postal_code

string

required

Fiscal postal code.

receipt_image

string

required

Receipt image as a base64 data URL (e.g., data:image/jpeg;base64,/9j/4AAQ...). When using multipart/form-data, send as a file upload instead.

string

Contact email address

phone_number

string

Phone number (e.g., +525512345678, 4431041040)

expense_description

string

Short description of the expense (max 50 characters)

Behavior

Validates the API key, organization, feature flag, and input fields
Looks up the RFC in the caller’s organization:
- Found — uses the existing profile
- Not found — creates a new member profile with the provided tax data, then submits the invoice
Resolves the tax regime for the invoice:
- If fiscal_regimen is in the request, uses it (validated against member’s regimes)
- If the member has a single regime, uses it automatically
- If the member has multiple regimes and the provided value is not valid, returns 400
Checks credits on the API key owner
Submits the invoice to the invoicing provider
Returns the invoice, member, and whether a new profile was created

Response

success

boolean

Whether the request was successful

data

object

Response data object

Show data properties

invoice

object

Invoice submitted to the invoicing provider

Show invoice properties

string

Invoice tracking ID (e.g., inv_abc123)

status

string

Always processing on creation

amount

number

Populated once the invoice is processed (initially null)

currency

string

Always MXN

vendor

string

Populated once the receipt is analyzed (initially null)

member_rfc

string

RFC used for this invoice

created_at

string

ISO 8601 creation timestamp

pdf_url

string

Populated once the CFDI is stamped (initially null)

xml_url

string

Populated once the CFDI is stamped (initially null)

member

object

Profile used (existing or newly created)

Show member properties

string

Profile UUID

name

string

Full name or business name

string

Email address (null if not provided)

phone_number

string

Phone number (null if not provided)

tax_id

string

RFC

org_id

string

Organization ID

created_at

string

Profile creation timestamp

created_profile

boolean

true if a new profile was created, false if an existing one was used

credits_remaining

number

API key owner’s remaining credits after this operation

curl -X POST https://api.usatimbre.com/api/timbre/create-invoice-full \
  -H "Authorization: Bearer tmb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_info": {
      "tax_id": "XAXX010101000",
      "cfdi_use": "G03",
      "taxpayer": "Juan Pérez García",
      "postal_code": "06600",
      "fiscal_regimen": "612"
    },
    "receipt_image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "success": true,
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "status": "processing",
      "amount": null,
      "currency": "MXN",
      "vendor": null,
      "member_rfc": "XAXX010101000",
      "created_at": "2024-01-21T10:30:00Z",
      "pdf_url": null,
      "xml_url": null
    },
    "member": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "phone_number": "+525512345678",
      "tax_id": "XAXX010101000",
      "org_id": "org_123456",
      "created_at": "2024-01-21T10:00:00Z"
    },
    "created_profile": true,
    "credits_remaining": 9
  }
}

Error Codes

Status	Code	Description
400	`MISSING_REQUIRED_FIELDS`	Missing `tax_id`, `cfdi_use`, `fiscal_regimen`, `taxpayer`, `postal_code`, or `receipt_image`
400	`INVALID_RFC_FORMAT`	RFC doesn’t match Mexican format (12-13 chars)
400	`INVALID_TAX_REGIME`	Invalid fiscal regime code
400	`INVALID_CFDI_FOR_REGIME`	CFDI usage code not valid for the resolved regime
400	`INVALID_REGIME`	Specified regime not in the member’s registered regimes
400	`INVALID_EMAIL`	Email format is invalid
400	`INVALID_PHONE_NUMBER`	Phone number format is invalid
401	—	Missing API key
401	`INVALID_API_KEY`	API key not found
403	`NO_ORGANIZATION`	API key owner has no organization
403	`FEATURE_DISABLED`	`api_keys_enabled` not active for the organization
403	`INSUFFICIENT_CREDITS`	No credits remaining
404	`RFC_NOT_FOUND`	RFC not found in organization
500	`LOOKUP_ERROR`	Error looking up RFC
500	`AUTH_USER_CREATION_FAILED`	Failed to create auth user for new profile
500	`PROFILE_CREATION_FAILED`	Failed to create profile record
500	`TAX_INFO_CREATION_FAILED`	Failed to create tax info record
500	`INTERNAL_ERROR`	Unexpected server error
503	`SERVICE_UNAVAILABLE`	Invoicing provider is temporarily unavailable

Create Invoice for Organization Get Invoice Details

​Overview

​Authentication

​Request Body

​Behavior

​Response

​Error Codes

Overview

Authentication

Request Body

Behavior

Response

Error Codes