API docs by Redocly

Tatem (1.0.0)

Download OpenAPI specification:

Gustavo Rago: contacto@tatem.mx URL: https://tatem.mx Terms of Service

Tatem API

Authentication

Obtain OAuth2 Token (Resource Owner Password Credentials Grant)

This endpoint generates an access token using the resource owner password credentials grant type. If the user has 2FA enabled, a temporary token will be returned and a verification code will be sent to their WhatsApp number. The user must then submit the verification code to complete the authentication process.

Authorizations:
OAuth2
Request Body schema: application/x-www-form-urlencoded
required
One of
grant_type
string
Value: "password"

Must be set to password for initial authentication.

username
string

The user's username.

password
string

The user's password.

client_id
string

The client ID issued by the OAuth server.

client_secret
string

The client secret issued by the OAuth server.

device_id
string

The trusted device ID.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request",
  • "error_description": "Missing client_id and/or client_secret parameters"
}

Refresh Access Token

Use a refresh token to obtain a new access token when the current one expires.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
string
Value: "refresh_token"

Must be set to refresh_token.

refresh_token
string

The refresh token issued during the initial authentication.

client_id
string

The client ID issued by the authorization server.

client_secret
string

The client secret issued by the authorization server.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Logout user

Invalidates the current access token and its associated refresh token

Authorizations:
OAuth2
Request Body schema: application/x-www-form-urlencoded
required
device_id
string

The trusted device ID.

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully logged out"
}

Request password reset

Requests a password reset for the user's email address

Request Body schema: application/json
required
email
string

The user's email address

passwordResetPath
string

The path to the password reset page. The [passwordResetCode] will be replaced with the actual password reset code.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "passwordResetPath": "/reset-password/[passwordResetCode]"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Password reset request sent"
}

Reset password

Resets the user's password

Request Body schema: application/json
required
passwordResetCode
string

The password reset code

password
string

The new password

Responses

Request samples

Content type
application/json
{
  • "passwordResetCode": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Password reset successfully"
}

Users

Get user information

Retrieves the authenticated user's information

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": "abcd",
  • "firstName": "John",
  • "lastName": "Sculley",
  • "username": "johnsculley@tatem.mx",
  • "email": "johnsculley@tatem.mx",
  • "emailVerifiedAt": "2024-12-01T17:24:59.146Z",
  • "whatsappNumber": "521234567890",
  • "whatsappNumberVerifiedAt": "2024-12-01T17:24:59.146Z",
  • "role": "accountant",
  • "createdAt": "2024-12-01T17:24:59.146Z",
  • "updatedAt": "2024-12-01T17:24:59.146Z",
  • "organizations": [
    ],
  • "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
  • "is2faEnabled": null,
  • "pendingInvitations": true
}

Create a new user

Creates a new user account with the provided information

Request Body schema: application/json
required
firstName
required
string non-empty

User's first name(s)

lastName
required
string non-empty

User's last name(s)

emailAddress
required
string <email>

User's email address

invitationCode
string

Code for accepting an invitation

userInvitationCode
string

Code for accepting an invitation to a user

password
string <password> >= 8 characters ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0...

Password must contain at least 8 characters, including lowercase, uppercase, number, and special character. Only required if googleIdToken isn't provided

googleIdToken
string

Google ID token of the user

country
string

Country of the user

region
string

ISO_3166-2 region of the user

city
string

City of the user

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "emailAddress": "user@example.com",
  • "invitationCode": "string",
  • "userInvitationCode": "string",
  • "password": "pa$$word",
  • "googleIdToken": "string",
  • "country": "MX",
  • "region": "MX-DF",
  • "city": "Mexico City"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "user": {
    },
  • "token": "string"
}

Update user information

Updates the authenticated user's information

Authorizations:
OAuth2
Request Body schema: application/json
required
firstName
string
lastName
string
emailAddress
string
whatsappNumber
string
currentPassword
string

The user's current password. Required if newPassword is provided.

newPassword
string
is2faEnabled
boolean

Indicates if the user has 2FA enabled.

isLastLogin
boolean

If set, the users' 'lastLoginAt' field will be updated with the current date.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "emailAddress": "string",
  • "whatsappNumber": "string",
  • "currentPassword": "string",
  • "newPassword": "string",
  • "is2faEnabled": true,
  • "isLastLogin": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "user": {
    },
  • "verifyEmail": true,
  • "verifyWhatsappNumber": true
}

Delete user

Deletes the authenticated user

Authorizations:
OAuth2
Request Body schema: application/json
required
password
string

The user's password

Responses

Request samples

Content type
application/json
{
  • "password": "password"
}

Response samples

Content type
application/json
{
  • "success": true
}

Update user default organization

Updates the authenticated user's default organization

Authorizations:
OAuth2
Request Body schema: application/json
required
defaultOrganizationId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User default organization updated"
}

Verify whatsapp number

Verifies the whatsapp number based on an invitation code linked to the user

Authorizations:
OAuth2
Request Body schema: application/json
required
code
required
string

The verification code sent to the user's WhatsApp number

Responses

Request samples

Content type
application/json
{
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Whatsapp number verified"
}

Verify email address

Verifies the email address based on an invitation code linked to the user

Authorizations:
OAuth2
Request Body schema: application/json
required
code
required
string

The verification code sent to the user's email address

Responses

Request samples

Content type
application/json
{
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Email address verified"
}

Sends the email address verification email

Sends the email address verification email to the user

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Email verification message sent"
}

Send WhatsApp verification code

Sends the WhatsApp verification code to the user's WhatsApp number

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Whatsapp verification code resent"
}

Create invitation code

Creates an invitation code for the user

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "invitationCode": "123456"
}

Organizations

Get organizations list

Retrieves a paginated list of organizations with optional filters

Authorizations:
OAuth2
query Parameters
provider_id
required
string <uuid>

ID of the provider to fetch organizations for

name
string

Filter organizations by name (case-insensitive partial match)

statuses
string
Example: statuses=pending,verified,not_verified

Comma-separated list of organization statuses to filter by

bank_account_id
string

Bank account Id assigned from the provider to filter the organizations for

include_invoice_preferences
boolean
Default: false

Include invoice preferences in the response

sort
string
Default: "name"
Enum: "name" "taxIdentifier" "status"

Field to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Enum: 10 30 60 100

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0
}

Create a new organization

Creates a new organization with the provided details

Request Body schema: application/json
required
commercialName
string

Commercial/trading name of the organization

industry
string

Industry of the organization

role
string
Enum: "owner" "accountant"

Role of the user creating the organization

Responses

Request samples

Content type
application/json
{
  • "commercialName": "string",
  • "industry": "string",
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "organization": {
    }
}

Get organization details by ID

Retrieves detailed information about a specific organization

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the organization to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "commercialName": "string",
  • "taxIdentifier": "string",
  • "taxRegimes": [
    ],
  • "cfdiUse": "G01",
  • "slug": "string",
  • "postalCode": "string",
  • "addressStreet": "string",
  • "addressNumber": "string",
  • "addressNumberInterior": "string",
  • "addressNeighborhood": "string",
  • "addressCity": "string",
  • "addressMunicipality": "string",
  • "addressState": "string",
  • "isEntity": true,
  • "taxIdentificationDocumentFile": {
    },
  • "taxIdentificationDocumentVerifiedAt": "2019-08-24T14:15:22Z",
  • "complianceDocumentFile": {
    },
  • "complianceDocumentVerifiedAt": "2019-08-24T14:15:22Z",
  • "economicActivities": [
    ],
  • "fielUploadedAt": "2019-08-24T14:15:22Z",
  • "csdUploadedAt": "2019-08-24T14:15:22Z",
  • "invoicesInbox": "string",
  • "status": "verified",
  • "completionStage": "none",
  • "facturapiValidatedAt": "2019-08-24T14:15:22Z",
  • "facturapiValidationErrors": "string",
  • "avatarUrl": "https://example.com/avatar.jpg",
  • "industry": "string",
  • "isDemoMode": true,
  • "contactFirstName": "Juan",
  • "contactLastName": "Pérez",
  • "contactEmailAddress": "juan.perez@example.com",
  • "contactPhoneNumber": "525512345678",
  • "contactJobTitle": "Gerente General",
  • "beneficiaryName": "Juan Pérez",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletionRequestedAt": "2019-08-24T14:15:22Z"
}

Update organization details

Update organization details

Request Body schema: application/json
required
commercialName
string

Commercial/trading name of the organization

industry
string

Industry of the organization

invoicesInbox
string

Inbox alias for deductibles

avatarUrl
string <uri>

URL of the organization's avatar image

isDemoMode
boolean
Default: false
contactFirstName
string

First name of the organization contact person

contactLastName
string

Last name of the organization contact person

contactEmailAddress
string <email>

Email address of the organization contact person

contactPhoneNumber
string

Phone number of the organization contact person (international format without +)

contactJobTitle
string

Job title of the organization contact person

Responses

Request samples

Content type
application/json
{
  • "commercialName": "Turistica Dinamica San Luis",
  • "industry": "Turistica",
  • "invoicesInbox": "facturas-turistica-dinamica-san-luis",
  • "avatarUrl": "https://example.com/avatar.jpg",
  • "isDemoMode": false,
  • "contactFirstName": "Juan",
  • "contactLastName": "Pérez",
  • "contactEmailAddress": "juan.perez@example.com",
  • "contactPhoneNumber": "525512345678",
  • "contactJobTitle": "Gerente General"
}

Response samples

Content type
application/json
{
  • "success": true
}

Request delete organization

Sends a request to delete an organization. The session data will be cleared and the organization will be deleted after 30 days.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Cancel organization deletion

Cancels the deletion request for an organization

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get organization fiscal data by slug

Retrieves fiscal data for a specific organization by its slug

query Parameters
slug
required
string
Example: slug=turistica-dinamica-san-luis

Slug of the organization

recaptcha_token
required
string
Example: recaptcha_token=1234567890

reCAPTCHA token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "organization": {
    }
}

Share organization details

Shares organization details with the user

Request Body schema: application/json
required
Array of objects
salesReceiptFileId
string

ID of the sales receipt file

paymentFormId
string

ID of the payment form. Required if salesReceiptFileId is provided.

cfdiUseId
string

ID of the CFDI use. Required if salesReceiptFileId is provided.

Responses

Request samples

Content type
application/json
{
  • "invites": [
    ],
  • "salesReceiptFileId": "cmabyd4st0000l804a8oay86u",
  • "paymentFormId": "99",
  • "cfdiUseId": "99"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 1,
  • "undeliverables": [
    ]
}

Update organization bank information

Updates an organization's bank information. The user must be associated with the organization and have permission to edit organization details.

Authorizations:
OAuth2
Request Body schema: application/json
required
bankIdentifier
required
string

Bank identifier

beneficiaryName
required
string

Name of the beneficiary

Responses

Request samples

Content type
application/json
{
  • "bankIdentifier": "123456789012345678",
  • "beneficiaryName": "Juan Pérez"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "organization": {
    }
}

Upload organization tax identification document

Uploads a tax identification document (PDF) for an organization. The user must be associated with the organization and have permission to edit organization details.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the organization

Request Body schema: multipart/form-data
required
taxIdentificationDocumentPdf
required
string <binary>

PDF file containing the tax identification document

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully",
  • "file": {
    }
}

Generate tax identification document from SAT using FIEL

Generates the tax identification document for the organization from SAT using FIEL

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to generate the tax identification document for

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Upload organization compliance document

Uploads a compliance document (PDF) for an organization. The user must be associated with the organization and have permission to edit organization details.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the organization

Request Body schema: multipart/form-data
required
complianceDocumentPdf
required
string <binary>

PDF file containing the compliance document

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully",
  • "file": {
    }
}

Generate compliance document from SAT using FIEL

Generates the compliance document for the organization from SAT using FIEL

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to generate the compliance document for

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get organization account balance

Retrieves the amount paid to the providers and the amount to pay within a specific date range. If no date range is provided, it returns the total amounts across all time.

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to get the account balance for

query Parameters
from
string <date>

Start date for filtering invoices by payment due date (format YYYY-MM-DD)

to
string <date>

End date for filtering invoices by payment due date (format YYYY-MM-DD)

Responses

Response samples

Content type
application/json
{
  • "paidAmount": 0,
  • "dueAmount": 0,
  • "totalAmount": 0,
  • "fromDate": "2019-08-24T14:15:22Z",
  • "toDate": "2019-08-24T14:15:22Z"
}

Upload FIEL files and password

Uploads the FIEL certificate and key files and the password for the organization

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to upload the FIEL files and password for

Request Body schema: application/json
required
fielCertFileId
string <uuid>
fielKeyFileId
string <uuid>
fielPassword
string

Responses

Request samples

Content type
application/json
{
  • "fielCertFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "fielKeyFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "fielPassword": "abcd123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "fiel_files_uploaded",
  • "error": "organization_already_exists"
}

Remove FIEL files and password

Removes the FIEL certificate and key files and the password for the organization

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to remove the FIEL files and password for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "fiel_files_removed"
}

Upload CSD files and password

Uploads the CSD certificate and key files and the password for the organization

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to upload the CSD files and password for

Request Body schema: application/json
required
csdCertFileId
string <uuid>
csdKeyFileId
string <uuid>
csdPassword
string

Responses

Request samples

Content type
application/json
{
  • "csdCertFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "csdKeyFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "csdPassword": "abcd123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "csd_files_uploaded"
}

Remove CSD files and password

Removes the CSD certificate and key files and the password for the organization

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

ID of the organization to remove the CSD files and password for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "csd_files_removed"
}

Get invoice preferences for an organization

Retrieves the invoice preferences for a specific organization. The user must have permission to access invoice preferences and be associated with the organization.

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

The ID of the organization

Responses

Response samples

Content type
application/json
{
  • "invoicePreferences": {
    }
}

Update invoice preferences for an organization

Updates the invoice preferences for a specific organization. The user must have permission to update invoice preferences and be associated with the organization.

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

The ID of the organization

Request Body schema: application/json
required
paymentMethods
Array of strings or null

Payment method codes

cfdiUses
Array of strings or null

CFDI use codes

paymentForms
Array of strings or null

Payment form codes

currencyCodes
Array of strings or null

Currency codes

paymentDay
integer or null [ 0 .. 6 ]

Day of the week for payment (0-6, where 0 is Sunday)

Array of objects or null

Allowed time periods for each day of the week to submit invoices

monthEndInvoiceDays
integer or null [ 0 .. 3 ]

Number of days before the end of the month to allow invoice uploads

isEfosClearanceMandatory
boolean or null

Whether the clearance is mandatory for the provider to upload invoices

isComplianceDocumentMandatory
boolean or null

Whether the compliance document is mandatory for the provider to upload invoices

numberOfMissingPendingInvoicePaymentsAllowed
integer or null

Number of missing pending invoice payments allowed for the provider to upload invoices

isBankingInformationMandatory
boolean or null

Whether the banking information is mandatory for the provider to upload invoices

isPurchaseOrderMandatory
boolean or null

Whether the purchase order is mandatory for the provider to upload invoices

isStampedAtCurrentMonthMandatory
boolean or null

Whether the provider can only upload invoices stamped at the current month

archivePaidInvoices
boolean or null

Whether to archive paid invoices

paymentDueAtAnchor
string or null
Enum: "createdAt" "stampedAt" "acceptedAt"

The anchor date for the payment due at

Responses

Request samples

Content type
application/json
{
  • "paymentMethods": [
    ],
  • "cfdiUses": [
    ],
  • "paymentForms": [
    ],
  • "currencyCodes": [
    ],
  • "paymentDay": 6,
  • "allowedInvoiceDays": [
    ],
  • "monthEndInvoiceDays": 3,
  • "isEfosClearanceMandatory": true,
  • "isComplianceDocumentMandatory": true,
  • "numberOfMissingPendingInvoicePaymentsAllowed": 0,
  • "isBankingInformationMandatory": true,
  • "isPurchaseOrderMandatory": true,
  • "isStampedAtCurrentMonthMandatory": true,
  • "archivePaidInvoices": true,
  • "paymentDueAtAnchor": "createdAt"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get deductible preferences for an organization

Retrieves the deductible preferences for a specific organization. The user must have permission to access deductible preferences and be associated with the organization.

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

The ID of the organization

query Parameters
expand
boolean

If set to true, the expanded preferences are returned

Responses

Response samples

Content type
application/json
{
  • "deductiblePreferences": {
    }
}

Update deductible preferences for an organization

Updates the deductible preferences for a specific organization. The user must have permission to update deductible preferences and be associated with the organization.

Authorizations:
OAuth2
path Parameters
organizationId
required
string <uuid>

The ID of the organization

Request Body schema: application/json
required
paymentMethods
Array of strings or null

Payment method codes

cfdiUses
Array of strings or null

CFDI use codes

paymentForms
Array of strings or null

Payment form codes

currencyCodes
Array of strings or null

Currency codes

archiveNotDeductibles
boolean or null

Whether to archive not deductible deductibles

archivePastDeductibles
boolean or null

Whether to archive past deductibles

autoApplyReasoning
boolean or null

Whether to auto apply reasoning

autoAcceptReasoning
boolean or null

Whether to auto accept reasoning

Responses

Request samples

Content type
application/json
{
  • "paymentMethods": [
    ],
  • "cfdiUses": [
    ],
  • "paymentForms": [
    ],
  • "currencyCodes": [
    ],
  • "archiveNotDeductibles": true,
  • "archivePastDeductibles": true,
  • "autoApplyReasoning": true,
  • "autoAcceptReasoning": true
}

Response samples

Content type
application/json
{
  • "success": true
}

UserOnOrganizations

Get users on organizations

Get users on organizations

Authorizations:
OAuth2
path Parameters
id
string <uuid>

ID of the organization. If not provided, the authenticated user's organizations will be returned.

query Parameters
name
string

Name of the organization to filter

commercial_name
string

Commercial name of the organization to filter

tax_identifier
string

Tax identifier of the organization to filter

is_entity
boolean

Whether the organization is an entity

sort
string
Enum: "name" "commercialName" "taxIdentifier" "isEntity"

Sort the organizations by a field

order
string
Enum: "asc" "desc"

Order the organizations by a field

page
integer

Page number

limit
integer

Page size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a user on an organization

Update a user on an organization

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the organization

query Parameters
user_id
string <uuid>

ID of the user on the organization

Request Body schema: application/json
required
isRead
boolean
isFavorite
boolean
role
string
Enum: "owner" "accountant" "collaborator" "assistant" "client" "readonly"

Role of the user on the organization. Accepted only if user_id is provided.

isDisabled
boolean

Responses

Request samples

Content type
application/json
{
  • "isRead": true,
  • "isFavorite": true,
  • "role": "owner",
  • "isDisabled": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a user on an organization

Delete a user on an organization

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the organization

query Parameters
user_id
required
string <uuid>

ID of the user on the organization

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Providers

Update provider credit days or bank account for an organization

Updates the credit days setting or providers' bank account for a specific provider-organization relationship. The user must be associated with both the provider and organization. Only a user managing the organization side of the relationship can update credit days and period. Only a user managing the provider side of the relationship can update the bank account, except the provider is being managed by the user's organization.

Authorizations:
OAuth2
query Parameters
update_invoices
boolean
Default: false

If set to 'true', all invoices that haven't been paid will have its paymentDueAt value recalculated according to the new setting for the provider

Request Body schema: application/json
required
Any of
organizationId
required
string <uuid>

ID of the organization

providerId
required
string <uuid>

ID of the provider

creditDays
integer [ 1 .. 365 ]

Number of credit days for the provider-organization relationship

creditPeriod
string
Enum: "d" "m" "y"

Credit period for the provider-organization relationship

bankAccountId
string or null <uuid>

Id of the provider's bank account to assign to this relationship

referenceNumber
string or null

Reference number for this client when doing payments to this provider

bankAccountInstructionsFileId
string or null

Bank account instructions PDF file id

Responses

Request samples

Content type
application/json
{
  • "providerOrganizations": [
    ],
  • "creditDays": 30,
  • "creditPeriod": "d",
  • "bankAccountId": "5b26b598-a880-4e32-8c41-126aa0206857",
  • "referenceNumber": "string",
  • "bankAccountInstructionsFileId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get credit days and bank account information for a provider-organization relationship.

Get the credit days setting and provider's bank account for a specific provider-organization relationship. The user must be associated with both the provider and organization.

Authorizations:
OAuth2
query Parameters
organization_id
required
any

Organization Id of the provider-organization relationship

provider_id
required
any

Provider Id of the provider-organization relationship

Responses

Response samples

Content type
application/json
{
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
  • "creditDays": 30,
  • "creditPeriod": "d",
  • "bankAccount": {
    },
  • "referenceNumber": "string",
  • "bankAccountInstructionsFile": {
    }
}

Catalogs

Get all tax regimes

Returns a list of all available tax regimes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get product keys

Returns a list of all available product keys

query Parameters
q
required
string >= 3 characters

The query to search for product keys

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get unit keys

Returns a list of all available unit keys

query Parameters
q
required
string >= 3 characters

The query to search for unit keys

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get CFDI usage codes

Returns a list of all valid CFDI usage codes and their descriptions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment forms

Returns a list of all valid payment forms and their descriptions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment methods

Returns a list of all valid payment methods and their descriptions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Mexican states

Returns a list of all Mexican states

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all countries

Returns a list of all countries

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all banks

Returns a list of all available banks

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all currency codes

Returns a list of all available currency codes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get geo data

Returns a list of all available geo data

query Parameters
postal_code
required
string

The postal code to get geo data for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get all taxes

Returns a list of all available taxes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all industries

Returns a list of all available industries

Responses

Response samples

Content type
application/json
[
  • "Manufactura y Maquila"
]

Check if a tax identifier is in the EFOS list

Checks if a tax identifier is in the EFOS list

query Parameters
tax_identifier
required
string

Tax identifiers to check, comma separated

organization_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get all job titles

Returns a list of all job titles

Responses

Response samples

Content type
application/json
[
  • "Dueño del negocio"
]

Files

Upload a file

Uploads a file to the system. The file type must be specified in the query parameters. Different file types have different allowed MIME types:

  • payment_proof: PNG, JPEG, JPG, PDF
  • invoice_xml: XML
  • invoice_pdf: PDF
  • tax_identification_document: PDF
  • purchase_order_pdf: PDF
  • good_standing_document: PDF
  • other: PDF
  • sales_receipt: PNG, JPEG, JPG,PDF
  • payment_proof_deductible: PNG, JPEG, JPG, PDF
  • fiel_cert_file: PEM
  • fiel_key_file: KEY
  • deductibles_upload_zip: ZIP
  • deductible_xml: Deductible XML
  • deductible_pdf: Deductible PDF
  • csd_cert_file: PEM
  • csd_key_file: KEY
  • expenses_upload_zip: ZIP
  • bank_account_instructions_pdf: PNG, JPEG, JPG, PDF
Authorizations:
OAuth2
query Parameters
type
required
string
Enum: "payment_proof" "invoice_xml" "invoice_pdf" "tax_identification_document" "purchase_order_pdf" "good_standing_document" "sales_receipt" "other" "payment_proof_deductible" "fiel_cert_file" "fiel_key_file" "deductibles_upload_zip" "deductible_xml" "deductible_pdf" "expenses_upload_zip" "bank_account_instructions_pdf"

Type of file being uploaded

Request Body schema: multipart/form-data
required
file
required
string <binary>

The file to upload

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully",
  • "file": {
    }
}

Get token for client uploads

Gets a token to upload a file to the system using client upload. The token is valid for 10 minutes.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "uploadToken": "string"
}

Get file details

Retrieves details for a specific file by ID. The user must have appropriate access permissions to view the file.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the file to retrieve

Responses

Response samples

Content type
application/json
{
  • "file": {
    }
}

Invitations to users

Invite users to join an organization

Authorizations:
OAuth2
Request Body schema: application/json
required
organizationIds
required
Array of strings <uuid> [ items <uuid > ]
role
required
string
Enum: "accountant" "collaborator" "client"

Role of the user in the organization

whatsappNumbers
Array of strings[ items non-empty ^[0-9]{12}$ ]
emailAddresses
Array of strings <email> [ items <email > ]
invitePath
required
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
{
  • "organizationIds": [
    ],
  • "role": "collaborator",
  • "whatsappNumbers": [
    ],
  • "emailAddresses": [
    ],
  • "invitePath": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "invitesSent": 5,
  • "failedInvites": [
    ]
}

Get invitation information sent to a user

Retrieves information associated with an invitation sent to a user.

query Parameters
user_invitation_code
required
string

The invitation code to lookup the information

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Join an organization or organizations

Links the user to the organization or organizations (provided a valid invitation code)

query Parameters
user_invitation_code
required
string

Invitation code to validate the organization creation

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Invitations to organizations

Invite organizations to join a provider

query Parameters
provider_id
required
string

ID of the provider sending the invitation

Request Body schema: application/json
required
Array ([ 1 .. 100 ] items)
whatsappNumber
string non-empty ^[0-9]{12}$

Organization's WhatsApp number

emailAddress
string <email>

Organization's email address

invitePath
required
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "invitesSent": 5
}

Get invitation information sent to an organization

Retrieves information associated with invitations sent to an organization. If invitation_code is provided, it retrieves information associated with a specific invitation. If provider_id is provided, it retrieves all invitations sent to the organization by the provider.

query Parameters
invitation_code
string

The invitation code to lookup the information

provider_id
string

The ID of the provider that sent the invitations

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete an organization invitation

Deletes an invitation using its invitation code

query Parameters
invitation_code
required
string

The invitation code to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Update an organization invitation

Updates an invitation's contact information using its invitation code

query Parameters
invitation_code
required
string

The invitation code to update

Request Body schema: application/json
required
non-empty
emailAddress
string <email>

Updated email address

whatsappNumber
string^[0-9]{12}$

Updated WhatsApp number

invitePath
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
{
  • "emailAddress": "user@example.com",
  • "whatsappNumber": "string",
  • "invitePath": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Resend an organization invitation

Resends an invitation to the same email and WhatsApp number using the existing invitation code

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code to resend

Request Body schema: application/json
required
non-empty
invitePath
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
{
  • "invitePath": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Link an organization to a provider

Links an invited organization to a provider using an invitation code

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code for linking the organization to the provider

organization_id
required
string

The ID of the organization to link to the provider

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Invitations to providers

Invite providers to join an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

ID of the organization sending the invitation

Request Body schema: application/json
required
Array ([ 1 .. 100 ] items)
whatsappNumber
string non-empty ^[0-9]{12}$

Provider's WhatsApp number

emailAddress
string <email>

Provider's email address

invitePath
required
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "invitesSent": 5
}

Get invitation information sent to a provider

Retrieves information associated with invitations sent to a provider. If invitation_code is provided, it retrieves information associated with a specific invitation. If organization_id is provided, it retrieves all invitations sent to the provider by the organization.

query Parameters
invitation_code
string

The invitation code to lookup the information

organization_id
string

The ID of the organization that sent the invitations

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a provider invitation

Deletes a provider invitation by its invitation code

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Update a provider invitation

Updates an existing provider invitation's email address or WhatsApp number

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code to update

Request Body schema: application/json
required
non-empty
emailAddress
string <email>

New email address for the invitation

whatsappNumber
string^[0-9]{12}$

New WhatsApp number for the invitation

invitePath
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
{
  • "emailAddress": "user@example.com",
  • "whatsappNumber": "string",
  • "invitePath": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Create invitation code by organization slug

Authorizations:
OAuth2
query Parameters
slug
required
string

Slug of the organization

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "invitationCode": "123e4567-e89b-12d3-a456-426614174000"
}

Resend a provider invitation

Resends an invitation to a provider using an existing invitation code. The user must have access to the organization that sent the original invitation.

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code to resend

Request Body schema: application/json
required
non-empty
invitePath
string non-empty

Path for the invitation URL

Responses

Request samples

Content type
application/json
{
  • "invitePath": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Link a provider to an organization

Links an invited provider to an organization using an invitation code

Authorizations:
OAuth2
query Parameters
invitation_code
required
string

The invitation code for linking the provider to the organization

provider_id
required
string

The ID of the provider to link to the organization

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Billing

Create a Stripe checkout session for subscription

Creates a Stripe checkout session for subscription. This endpoint is intended to be used with Stripe embedded elements. The user must have permission to access subscriptions. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:
OAuth2
query Parameters
success_path
required
string

Path to redirect to after successful payment

organization_id
required
string

Organization ID

promotion_code
string

The promotion code to apply to the subscription

Responses

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

Create a Stripe checkout session for one-time payment

Creates a Stripe checkout session for one-time payment. This endpoint is intended to be used with Stripe embedded elements. The user must have permission to access balance. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:
OAuth2
query Parameters
success_path
required
string

Path to redirect to after successful payment

organization_id
required
string

Organization ID

amount
required
number >= 100

Amount to pay

Responses

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

Get the status of a Stripe checkout session

Retrieves the status of a Stripe checkout session. The user must have permission to access subscriptions.

Authorizations:
OAuth2
query Parameters
session_id
required
string

Stripe checkout session ID

Responses

Response samples

Content type
application/json
{
  • "isPaymentSuccessful": true,
  • "status": "complete",
  • "amountTotal": 0,
  • "currency": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "paymentMethod": {
    },
  • "isSubscription": true
}

Create a Stripe checkout session to update payment method in Stripe

Creates a Stripe checkout session to update payment method in Stripe. The user must have permission to access billing. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:
OAuth2
query Parameters
success_path
required
string

Path to redirect to after successful payment

organization_id
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

Get taxes for checkout session

Calculates taxes for a checkout session based on the amount and organization type. The taxes calculation depends on whether the organization is an entity or not. For entities, additional withholding taxes (ISR and VAT withholding) are applied. The user must have permission to access the organization.

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID

amount
required
number >= 0.01

Amount to calculate taxes for (must be greater than 0)

percent_off
number [ 1 .. 100 ]

Discount % of the amount

Responses

Response samples

Content type
application/json
{
  • "taxes": {
    }
}

Get billing account

Retrieve the billing account details for the authenticated user

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "billingAccount": {
    }
}

Create or update billing account

Create a new billing account or update an existing one for the authenticated user

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID

Request Body schema: application/json
required
name
required
string

Legal name of the company

commercialName
required
string

Commercial name of the company

taxIdentifier
required
string

RFC of the company

taxRegime
required
string

Tax regime code

postalCode
required
string

Postal code (must be 5 digits)

cfdiUse
required
string

CFDI use code

Responses

Request samples

Content type
application/json
{
  • "name": "Razón Social",
  • "commercialName": "Nombre Comercial",
  • "taxIdentifier": "XAXX010101000",
  • "taxRegime": "601",
  • "postalCode": "12345",
  • "cfdiUse": "G03"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "billingAccount": {
    }
}

Get organization subscriptions

Retrieve all subscriptions for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID

Responses

Response samples

Content type
application/json
{
  • "didHaveSubscription": true,
  • "subscriptions": [
    ]
}

Cancels a subscription

Cancels a subscription for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID

Request Body schema: application/json
required
password
required
string non-empty

User's password

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "subscription_scheduled_for_cancellation"
}

Create a trial subscription or a paid subscription

Create a trial subscription or a paid subscription for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

The ID of the organization

payment_method_id
string <uuid>

The ID of the payment method to use for the subscription. If not payment method is provided, the default payment method will be used.

promotion_code
string

The promotion code to apply to the subscription

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request_body"
}

Update a subscription promotion code

Update an existing subscription with a new promotion code

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

The ID of the organization

promotion_code
required
string

The promotion code to apply to the subscription

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request_body"
}

Resume a paused subscription

Resume a paused subscription for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

The ID of the organization

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Answer survey

Submit a survey answer for the organization

Authorizations:
OAuth2
Request Body schema: application/json
required
answer
required
string [ 1 .. 1000 ] characters

The survey answer text

organizationId
required
string <uuid>

The ID of the organization

Responses

Request samples

Content type
application/json
{
  • "answer": "string",
  • "organizationId": "cmgy9k6u1000l1n3sx22aw62r"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get billing invoices

Retrieve all invoices for the authenticated user

Authorizations:
OAuth2
query Parameters
created_at_from
string <date-time>

Filter billing invoices created after this date

created_at_to
string <date-time>

Filter billing invoices created before this date

is_subscription
any
page
integer
Default: 1

Page number

limit
any

Number of invoices per page

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "invoices": [
    ]
}

Download billing invoices as ZIP

Download multiple billing invoices as a ZIP file containing their PDF files

Authorizations:
OAuth2
Request Body schema: application/json
required
billingInvoiceIds
required
Array of strings [ 1 .. 100 ] items

Array of billing invoice IDs to download

Responses

Request samples

Content type
application/json
{
  • "billingInvoiceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "file_1234567890",
  • "filename": "Facturas Tátem - 25 oct 25 - ABC123456789.zip",
  • "type": "billing_invoice_zip",
  • "status": "processing",
  • "createdAt": "2023-10-25T10:30:00Z"
}

Get payment methods

Get the payment methods for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

The ID of the organization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete payment method

Delete a payment method for an organization

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

The ID of the payment method to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Set default payment method

Set a payment method as the default for an organization

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

The ID of the payment method to set as default

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get promotion code details

Validate a Stripe promotion code and retrieve the discount percentage

Authorizations:
OAuth2
query Parameters
promotion_code
required
string

The promotion code to validate

Responses

Response samples

Content type
application/json
{
  • "percent_off": 20,
  • "duration": "forever",
  • "duration_in_months": 6
}

Deductibles

Get deductibles list

Retrieves a paginated list of deductibles with optional filters

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch deductibles for

uuid
string <uuid>

Filter by deductible UUID

folio_number
string
Example: folio_number=1234567890,1234567891

Comma separated list of folio numbers to filter by

statuses
string
Example: statuses=deductible,not_deductible,not_valid

Comma-separated list of deductible statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

created_at_period
string
Example: created_at_period=2025-01

Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

sort
string
Default: "uuid"
Enum: "uuid" "grossPriceAmount" "status" "createdAt" "updatedAt" "issuerName" "issuedAt" "stampedAt"

Comma-separated list of fields to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Comma-separated list of sort orders to sort by. The number of values in this parameter must match exactly the number of values in the 'order' parameter.

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 30
Enum: 10 30 60 100

Number of items per page

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

is_entity
boolean
Default: false

Filter by entity status

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "grossPriceAmount": 0,
  • "taxesAmount": [
    ],
  • "unreadCount": 0,
  • "totalPages": 0,
  • "totalCount": 0,
  • "itemCount": 0,
  • "itemsWithChartCount": 0
}

Update deductibles

Updates a list of deductibles

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch deductibles for

uuid
string <uuid>

Filter by deductible UUID

statuses
string
Example: statuses=deductible,not_deductible,not_valid

Comma-separated list of deductible statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

created_at_period
string
Example: created_at_period=2025-01

Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

is_entity
boolean
Default: false

Filter by entity status

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Request Body schema: application/json
required
deductibleIds
Array of strings <uuid> <= 100 items [ items <uuid > ]
archive
boolean

Whether to archive (true) or unarchive (false) the deductible

status
string
Enum: "deductible" "review" "semi_deductible" "not_deductible"
isRead
boolean

Responses

Request samples

Content type
application/json
{
  • "deductibleIds": [
    ],
  • "archive": false,
  • "status": "deductible",
  • "isRead": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "archivedDeductibles": [
    ]
}

Create a new deductible

Creates a new deductible by uploading XML and PDF files

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization the deductible is for

Request Body schema: multipart/form-data
required
invoiceXml
required
string <binary>

XML file containing the CFDI invoice data

invoicePdf
string <binary>

PDF version of the invoice

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "deductible": {
    },
  • "message": "File uploaded successfully"
}

Upload deductibles as zip

Upload deductibles as zip

Authorizations:
OAuth2
Request Body schema: application/json
required
deductiblesUploadZipId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "deductiblesUploadZipId": "bcd5f9d8-7a58-4133-b91e-ea57672ab67c"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete multiple deductibles

Deletes multiple deductibles

Authorizations:
OAuth2
Request Body schema: application/json
required
deductibleIds
required
Array of strings <uuid> non-empty [ items <uuid > ]
convertToInvoice
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "deductibleIds": [
    ],
  • "convertToInvoice": false
}

Response samples

Content type
application/json
{
  • "success": true
}

Get deductibles balance

Retrieves the balance of deductibles for an organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch deductibles for

uuid
string <uuid>

Filter by deductible UUID

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

created_at_period
string
Example: created_at_period=2025-01

Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issuer_name
string
Example: issuer_name=test

Filter by issuer name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

is_entity
boolean
Default: false

Filter by entity status

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "grossPriceAmount": 0,
  • "taxesAmount": [
    ]
}

Get top charts for deductibles

Retrieves the top charts for deductibles

query Parameters
organization_id
string <uuid>

ID of the organization to fetch deductibles for

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new deductible batch

Creates a new deductible batch

query Parameters
organization_id
required
string <uuid>

ID of the organization to delete the deductible sync for

Request Body schema: application/json
required
fromDate
string <date>

Start date of the batch

toDate
string <date>

End date of the batch

paymentForm
string
Enum: "PUE" "PPD"

Payment form to filter the batch

taxIdentifier
string

Tax identifier to filter the batch

taskType
string
Default: "deductibles"
Enum: "deductibles" "invoices"

The task type for the batch

Responses

Request samples

Content type
application/json
{
  • "fromDate": "2019-08-24",
  • "toDate": "2019-08-24",
  • "paymentForm": "PUE",
  • "taxIdentifier": "string",
  • "taskType": "deductibles"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Get deductible sync

Retrieves a list of deductibles syncs

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch deductibles syncs for

Responses

Response samples

Content type
application/json
{
  • "fromDateAt": "2019-08-24",
  • "paymentForm": "PUE",
  • "taxIdentifier": "string",
  • "scheduledDays": [
    ],
  • "taskType": "deductibles",
  • "mode": "every"
}

Create a new deductible sync

Creates a new deductible sync

query Parameters
organization_id
required
string <uuid>

ID of the organization to delete the deductible sync for

Request Body schema: application/json
required
fromDate
string <date>

Start date of the sync

scheduledDays
Array of numbers

If mode is "on": schedule sync on the days specified in scheduledDays (only values 1, 7, 15, 20, 0 are allowed, 0 representing last day of the month) If mode is "every": schedule sync every X days specified in scheduledDays (only one value between 1 and 30 is allowed)

mode
string
Enum: "every" "on"

If mode is "on": schedule sync on the days specified in scheduledDays If mode is "every": schedule sync every X days specified in scheduledDays

paymentForm
string
Enum: "PUE" "PPD"

Payment form to filter the sync

taxIdentifier
string

Tax identifier to filter the sync

taskType
string
Default: "deductibles"
Enum: "deductibles" "invoices"

The type of the task the sync will create

Responses

Request samples

Content type
application/json
{
  • "fromDate": "2019-08-24",
  • "scheduledDays": [
    ],
  • "mode": "every",
  • "paymentForm": "PUE",
  • "taxIdentifier": "string",
  • "taskType": "deductibles"
}

Response samples

Content type
application/json
{
  • "type": null,
  • "properties": null
}

Delete a deductible sync

Deletes the configured deductible sync for the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to delete the deductible sync for

task_type
required
any

The task type to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get deductible details by ID

Retrieves detailed information about a specific deductible

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "processing",
  • "statusMode": "manual",
  • "uuid": "string",
  • "series": "string",
  • "folioNumber": 0,
  • "netPriceAmount": 0,
  • "grossPriceAmount": 0,
  • "discount": 0,
  • "cfdiUse": "string",
  • "paymentMethod": "string",
  • "paymentForm": "string",
  • "issuerName": "string",
  • "issuerTaxIdentifier": "string",
  • "issuerTaxRegime": "string",
  • "issuerPostalCode": "string",
  • "isEntity": true,
  • "recipientName": "string",
  • "recipientTaxIdentifier": "string",
  • "recipientTaxRegime": "string",
  • "recipientPostalCode": "string",
  • "recipientTaxRegimes": [
    ],
  • "recipientEconomicActivities": [
    ],
  • "currencyCode": "string",
  • "isCancelled": true,
  • "readAt": "2019-08-24T14:15:22Z",
  • "xmlFile": {
    },
  • "pdfFile": {
    },
  • "pdfFileVerifiedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "stampedAt": "2019-08-24T14:15:22Z",
  • "organization": {
    },
  • "reasoning": {
    },
  • "items": [
    ],
  • "taxes": [
    ]
}

Update deductible

Updates a deductible

path Parameters
id
required
string <uuid>

ID of the deductible to update

Request Body schema: application/json
required
notes
string
status
string
Enum: "deductible" "review" "not_deductible"
paymentProofFileId
string <uuid>
invoicePdfFileId
string <uuid>
isRead
boolean
chartId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "notes": "Notas del deducible",
  • "status": "deductible",
  • "paymentProofFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "invoicePdfFileId": "123e4567-e89b-12d3-a456-426614174000",
  • "isRead": true,
  • "chartId": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "archived": true
}

Delete deductible

Deletes a deductible

path Parameters
id
required
string <uuid>

ID of the deductible to delete

query Parameters
convert_to_invoice
boolean
Default: false

If set to 'true', the deductible will be converted to an Invoice and a new entry for a Provider prospect will be created (if it didn't exist yet) for this organization

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Generate PDF for deductible

Generates a PDF for a deductible

path Parameters
id
required
string <uuid>

ID of the deductible to generate PDF for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "pdfFile": {
    }
}

Get providers list from deductibles

Retrieves a list of providers from all deductibles of the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch providers for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get product keys list from deductibles

Retrieves a list of product keys from all deductibles of the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch product keys for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment forms list from deductibles

Retrieves a list of payment forms from all deductibles of the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch payment forms for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment methods list from deductibles

Retrieves a list of payment methods from all deductibles of the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch payment methods for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get CFDI uses list from deductibles

Retrieves a list of CFDI uses from all deductibles of the organization

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch CFDI usees for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get entity types list from deductibles

Retrieves a list of entity types from all deductibles of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch entity types for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download deductibles as a zip or xls file

Downloads a zip or xls file containing all selected deductibles

Authorizations:
OAuth2
query Parameters
format
required
string
Enum: "zip" "xls"

Format of the file to download

deductible_ids
string

Comma separated list of IDs of the deductibles to download. If this parameter is specified, all other query filters (except 'format') will be ignored.

organization_id
string <uuid>

ID of the organization to fetch deductibles for

uuid
string <uuid>

Filter by deductible UUID

statuses
string
Example: statuses=deductible,not_deductible,not_valid

Comma-separated list of deductible statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

created_at_period
string
Example: created_at_period=2025-01

Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

is_entity
boolean
Default: false

Filter by entity status

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pathname": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "downloadUrl": "string",
  • "type": "string",
  • "filename": "string",
  • "url": "string",
  • "status": "processing"
}

Deductible Items

Update deductible item

Updates a deductible item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible item to update

Request Body schema: application/json
required
status
string
Enum: "deductible" "review" "not_deductible"
chartId
string or null <uuid>

ID of the chart to assign to the deductible item.

chartReasoningConfirmed
boolean

Used to mark when a human has confirmed the chart reasoning.

Responses

Request samples

Content type
application/json
{
  • "status": "deductible",
  • "chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
  • "chartReasoningConfirmed": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Deductible item updated successfully"
}

Deductible Rules

Get deductible rules

Get deductible rules

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch deductible rules for

sort
string
Default: "priority"
Enum: "description" "priority" "createdAt" "updatedAt"

Field to sort by

order
string
Default: "asc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Enum: 10 30 60 100

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "total": 0
}

Enable or disable a deductible rule

Enable or disable a deductible rule

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible rule to enable or disable

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch deductible rules for

Request Body schema: application/json
required
isEnabled
boolean

Responses

Request samples

Content type
application/json
{
  • "isEnabled": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Deductible Reasons

Create a new deductible reason

Create a new deductible reason

Authorizations:
OAuth2
Request Body schema: application/json
required
Array
deductibleId
string <uuid>

ID of the deductible

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true
}

Accept or reject a deductible reason

Accept or reject a deductible reason

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible reason to accept or reject

Request Body schema: application/json
required
status
string
Enum: "deductible" "not_deductible"
notes
string

Responses

Request samples

Content type
application/json
{
  • "status": "deductible",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Accept or reject a deductible item reason

Accept or reject a deductible item reason

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible item reason to accept or reject

Request Body schema: application/json
required
status
string
Enum: "deductible" "not_deductible"
notes
string

Responses

Request samples

Content type
application/json
{
  • "status": "deductible",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Rate a deductible item reason

Rate a deductible item reason

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible item reason to rate

Request Body schema: application/json
required
rating
string
Enum: "positive" "negative" "neutral"

Rating of the deductible item reason

Responses

Request samples

Content type
application/json
{
  • "rating": "positive"
}

Response samples

Content type
application/json
{
  • "success": true
}

Rate a deductible reason

Rate a deductible reason

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the deductible reason to rate

Request Body schema: application/json
required
rating
string
Enum: "positive" "negative" "neutral"

Rating of the deductible reason

Responses

Request samples

Content type
application/json
{
  • "rating": "positive"
}

Response samples

Content type
application/json
{
  • "success": true
}

Consumables

Get consumables

Get consumables of the organization for the period

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch consumables for

period
string

Period to query the consumables. If not provided, the consumables for the current period are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get consumable consumptions

Get paginated consumable consumptions of the organization with filtering and sorting capabilities

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch consumable consumptions for

page
integer >= 1
Default: 1

Page number for pagination (default is 1)

limit
integer [ 1 .. 100 ]
Default: 30

Number of items per page (default is 30)

sort
string
Default: "createdAt"
Enum: "createdAt" "count" "unitPrice" "consumableKey"

Field to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

created_at_from
string <date-time>

Filter consumable consumptions created from this date (ISO 8601 format)

created_at_to
string <date-time>

Filter consumable consumptions created up to this date (ISO 8601 format)

consumable_key
string

Filter by consumable key (case-insensitive partial match)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0
}

Charts

Get charts

Get charts of the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch charts for

Responses

Response samples

Content type
application/json
{
  • "charts": [
    ],
  • "lastUpdatedAt": "2019-08-24T14:15:22Z"
}

Upload a XLS file to update the charts of the organization

Uploads and processes a XLS file to update the charts of the organization. The file must have the following structure:

  • Column A: Code
  • Column B: Description (optional)
Authorizations:
OAuth2
query Parameters
organization_id
required
any

ID of the organization to update the charts for

mode
string
Default: "update"
Enum: "update" "replace"

Mode of the operation

Request Body schema: multipart/form-data
required
file
required
string <binary>

The file to upload

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "updatedCharts": [
    ],
  • "updateCount": 10
}

Delete charts

Delete charts of the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to delete charts for

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get items that need chart classification

Returns items (invoice items, deductible items, expense items) that need chart classification.

By default, returns items that have no chart assigned. When max_confidence_score is provided, also includes items that have a chart assigned with 'reasoning' mode but with a confidence score at or below the threshold (indicating they may need reclassification).

Items with 'reasoning' mode that have already been confirmed by a human (chartReasoningConfirmedAt or chartAsPayableReasoningConfirmedAt is not null) are excluded from the results, as they no longer need classification.

This endpoint is useful for building a queue of items that need human review for chart assignment.

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch items for

page
integer >= 1
Default: 1

Page number for pagination (1-based)

limit
integer [ 1 .. 100 ]
Default: 10

Number of items per page

type
string
Enum: "invoice" "invoice_as_provider" "deductible" "expense"

Filter by item type

max_confidence_score
number <float> [ 0 .. 1 ]
Example: max_confidence_score=0.5

Maximum confidence score threshold. When provided, also returns items that have a chart assigned with 'reasoning' mode but with confidence score at or below this value. Items with 'manual' or 'reinforcement' mode are excluded from this filter.

min_confidence_score
number <float> [ 0 .. 1 ]
Example: min_confidence_score=0.8

Minimum confidence score threshold. When provided, only returns items that have a chart assigned with confidence score at or above this value. Uses the higher of chartConfidenceScore or chartAsPayableConfidenceScore for comparison.

include_assigned
boolean
Default: false
Example: include_assigned=true

If true, includes all items regardless of chart assignment status. When false (default), only returns items that need classification (no chart assigned or low confidence reasoning charts).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get concepts that need chart classification

Returns concepts that need chart classification. Concepts are templates that store item attributes (description, itemKey, issuerName, recipientName) along with their embeddings and chart assignments.

By default, returns concepts that have no chart assigned. When max_confidence_score is provided, also includes concepts that have a chart assigned with 'reasoning' mode but with a confidence score at or below the threshold (indicating they may need reclassification).

When include_assigned is true, returns all concepts regardless of chart assignment status.

This endpoint is useful for building a queue of concepts that need human review for chart assignment.

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch concepts for

page
integer >= 1
Default: 1

Page number for pagination (1-based)

limit
integer [ 1 .. 100 ]
Default: 10

Number of concepts per page

max_confidence_score
number <float> [ 0 .. 1 ]
Example: max_confidence_score=0.5

Maximum confidence score threshold. When provided, also returns concepts that have a chart assigned with 'reasoning' mode but with confidence score at or below this value. Concepts with 'manual' or 'reinforcement' mode are excluded from this filter.

min_confidence_score
number <float> [ 0 .. 1 ]
Example: min_confidence_score=0.8

Minimum confidence score threshold. When provided, only returns concepts that have a chart assigned with confidence score at or above this value. Uses the higher of chartConfidenceScore or chartAsPayableConfidenceScore for comparison.

include_assigned
boolean
Default: false
Example: include_assigned=true

If true, includes all concepts regardless of chart assignment status. When false (default), only returns concepts that need classification (no chart assigned or low confidence reasoning charts).

chart_mode_filter
string
Enum: "none" "manual" "reasoning"
Example: chart_mode_filter=none

Filter concepts by chart assignment mode. Valid values:

  • none: Returns concepts with no chart assigned whatsoever
  • manual: Returns concepts with charts assigned by 'manual' or 'reinforcement' mode
  • reasoning: Returns concepts with charts assigned by 'reasoning' mode

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get count of items that can be reclassified for a concept

Returns the count of items that match this concept and can be reclassified when a chart is manually assigned to the concept. This includes:

  • Items with 'reasoning' chartMode (or chartAsPayableMode for invoices) that would be updated
  • Items with no chart assigned (chartId is null) or no chartAsPayable assigned (chartAsPayableId is null)

The response also provides a breakdown by confidence score threshold (0.8):

  • Items below the threshold (confidence < 0.8 or null) - these are items that were previously assigned with low confidence or have no chart assigned
  • Items above the threshold (confidence >= 0.8) - these are items that were previously assigned with high confidence but are in 'reasoning' mode

This endpoint is useful for showing users how many items would be affected if they manually assign a chart to a concept, and which items were previously below or above the confidence threshold.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the concept

Responses

Response samples

Content type
application/json
{
  • "chartCount": 0,
  • "chartAsPayableCount": 0,
  • "totalCount": 0,
  • "chartCountBelowThreshold": 0,
  • "chartCountAboveThreshold": 0,
  • "chartAsPayableCountBelowThreshold": 0,
  • "chartAsPayableCountAboveThreshold": 0,
  • "hasEnoughBalance": true,
  • "consumablesToConsume": 0,
  • "actualUnitsToDebit": 0,
  • "amountToDebit": 0
}

Update concept chart assignments

Updates chart assignments for a concept. Can assign or update charts, and can confirm reasoning for charts assigned with 'reasoning' mode.

When assigning a chart:

  • If no chart was assigned before, sets chartMode to 'manual'
  • If chart was assigned with 'reasoning' mode, sets chartMode to 'reinforcement'
  • Otherwise, sets chartMode to 'manual'

When a chart (or chartAsPayable) is assigned to a concept, all matching items that can be reclassified are automatically updated:

  • Items with 'reasoning' chartMode (or chartAsPayableMode) are updated with the new chart assignment
  • Items with no chart assigned (chartId is null) or no chartAsPayable assigned (chartAsPayableId is null) are updated with the new chart assignment

For invoice concepts:

  • chartId is assigned by providerId (organization acting as provider)
  • chartAsPayableId is assigned by organizationId (organization acting as recipient)

For deductible/expense concepts:

  • chartId is assigned by organizationId
Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the concept to update

Request Body schema: application/json
required
chartId
string or null <uuid>

Chart ID to assign. Set to null to remove the chart assignment.

chartAsPayableId
string or null <uuid>

Chart as payable ID to assign (only for invoice concepts). Set to null to remove the assignment.

chartReasoningConfirmed
boolean

Set to true to confirm the reasoning for the chart. Can only be set when chartMode is 'reasoning' and chartId is not null. Cannot be set when chartId is being updated simultaneously.

chartAsPayableReasoningConfirmed
boolean

Set to true to confirm the reasoning for the chart as payable. Can only be set when chartAsPayableMode is 'reasoning' and chartAsPayableId is not null. Cannot be set when chartAsPayableId is being updated simultaneously.

Responses

Request samples

Content type
application/json
{
  • "chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
  • "chartAsPayableId": "e5cbc150-426d-4c07-8f16-2678e9338d6e",
  • "chartReasoningConfirmed": true,
  • "chartAsPayableReasoningConfirmed": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "itemsUpdated": 8,
  • "chartItemsUpdated": 5,
  • "chartAsPayableItemsUpdated": 3
}

Notifications

Get notifications token

Retrieves the authenticated user's notifications token

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "keyName": "kQII_Q._NT4GA",
  • "clientId": "cm8s41v8g000xyybohttlxeu2",
  • "capability": "{\"org:a4897663-13e8-4e60-94ad-b97bfc29fdcc:notifications\":[\"subscribe\"]}",
  • "timestamp": 1744874357402,
  • "nonce": "8850976877819143",
  • "mac": "cRVhv3/+a2BucuMHBQlVLQyJvGYVQlORDoP8gQ/93CQ="
}

Get user notifications

Retrieves the authenticated user's notifications

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark notifications as read

Marks the specified notifications as read

Authorizations:
OAuth2
Request Body schema: application/json
required
Array
notificationId
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 1
}

Clear notifications

Clear the specifiednotifications

Authorizations:
OAuth2
Request Body schema: application/json
required
Array
notificationId
required
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 1
}

Status

Get status

Get status

Responses

Response samples

Content type
application/json
{
  • "daysSinceLastSync": 10,
  • "syncLastResponseAt": "2025-06-15T12:00:00.000Z"
}

Stats

Get home statistics

Retrieves basic statistics including counts of providers, expenses, invoices, foreign invoices, reasoned items, and government invoices.

Responses

Response samples

Content type
application/json
{
  • "stats": {
    }
}

Trusted Devices

Create a trusted device

Create a trusted device

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "deviceId": "123e4567-e89b-12d3-a456-426614174000"
}

Provider Prospects

Get provider prospects for an organization

Retrieves a list of provider prospects for the specified organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch provider prospects for

q
string

Filter by name, commercialName or taxIdentifier

name
string

Name of the provider prospect

taxIdentifier
string

Tax identifier of the provider prospect

commercialName
string

Commercial name of the provider prospect

isInEfos
boolean
Default: null

Whether the provider prospect is in Efos

incomplete
boolean
Default: null

Filter by incomplete provider prospects according to the organization's invoice preferences

sort
string
Default: "name"
Enum: "name" "taxIdentifier" "organization.status" "createdAt" "organizations.isMain"

Field(s) to sort by, comma separated

order
string
Default: "asc"
Enum: "asc" "desc"

Sort order for each field specified in 'sort', comma separated. Must be the same number of values as 'sort', otherwise an HTTP 400 'mismatched_sort_order_length' will be returned.

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Enum: 10 30 60 100

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "notVerifiedCount": 0,
  • "incompleteCount": 0,
  • "mainCount": 0,
  • "grossPriceAmount": 0,
  • "numberOfInvoices": 0,
  • "totalPages": 0,
  • "totalCount": 0
}

Update main provider prospects list

Updates the main provider prospects list for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to update provider prospects for

Request Body schema: application/json
required
providerProspectIds
Array of strings <uuid> [ items <uuid > ]
isMain
boolean

Whether to set the provider prospects as main or not

allowDisable
boolean

When the number of main provider prospects is exceeded for the organization, setting this value to true will allow to automatically disable other provider prospects with the less amount of existing invoices.

Responses

Request samples

Content type
application/json
{
  • "providerProspectIds": [
    ],
  • "isMain": true,
  • "allowDisable": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "providerProspectsToDisable": [
    ],
  • "providerProspectsToEnable": [
    ]
}

Download provider prospects as Excel

Downloads a list of provider prospects for the specified organization as an Excel file.

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to download provider prospects for

provider_prospect_ids
string

Comma separated list of provider prospect ids to include in the downloaded Excel file. If no ids are provided, all providers are included.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pathname": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "downloadUrl": "string",
  • "type": "string",
  • "filename": "string",
  • "url": "string",
  • "status": "processing"
}

Get a provider prospect

Retrieves a provider prospect by ID

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the provider prospect to fetch

query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch provider prospect for

Responses

Response samples

Content type
application/json
{
  • "providerProspect": {
    },
  • "amountPaid": 0,
  • "numberOfInvoicesPaid": 0,
  • "numberOfInvoicesPending": 0
}

Create a new organization for a provider prospect

Creates a new organization for a provider prospect

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the provider prospect

query Parameters
organization_id
required
string <uuid>

ID of the organization creating the new organization for the provider prospect

Request Body schema: application/json
required
commercialName
string

Commercial/trading name of the organization

industry
string

Industry of the organization

Responses

Request samples

Content type
application/json
{
  • "commercialName": "string",
  • "industry": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "organization": {
    }
}

Organization Prospects

Get organization prospects for a provider

Retrieves a list of organization prospects for the specified provider

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch provider prospects for

q
string

Filter by name, commercialName or taxIdentifier

sort
string
Default: "name"
Enum: "name" "taxIdentifier" "organization.status" "createdAt"

Field to sort by

order
string
Default: "asc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Enum: 10 30 60 100

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0
}

Invoices

Get invoices list

Retrieves a paginated list of invoices with optional filters

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890,1234567891

Comma separated list of folio numbers to filter by

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

sort
string
Default: "statusCode"
Enum: "uuid" "grossPriceAmount" "organization.taxIdentifier" "organization.name" "issuerName" "recipientName" "status" "statusCode" "sentAt" "createdAt" "updatedAt" "paymentDueAt" "stampedAt" "folioNumber" "series"

Comma-separated list of fields to sort by

order
string
Default: "asc"
Enum: "asc" "desc"

Comma-separated list of sort orders to sort by. The number of values in this parameter must match exactly the number of values in the 'order' parameter.

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 30
Enum: 10 30 60 100

Number of items per page

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXT"
Example: payment_method=PPD,PUE

Filter by payment methods, comma separated

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0,
  • "unreadCount": 0,
  • "amountDue": 0,
  • "amountPastDue": 0,
  • "amountPaid": 0
}

Create a new invoice

Creates a new invoice by uploading XML and PDF files

Authorizations:
OAuth2
query Parameters
provider_id
string <uuid>

ID of the provider creating the invoice

organization_id
string <uuid>

ID of the organization the invoice is for

Request Body schema: multipart/form-data
required
invoiceXml
required
string <binary>

XML file containing the CFDI invoice data

invoicePdf
string <binary>

PDF version of the invoice

purchaseOrderPdf
string <binary>

Optional PDF or image file of the purchase order

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "invitationCode": "string",
  • "organization": {
    }
}

Update invoices

Updates a list of invoices

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXI"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Request Body schema: application/json
optional
invoiceIds
Array of strings <uuid> <= 100 items [ items <uuid > ]

IDs of the invoices to update. If this parameter is specified, query filters will be ignored.

archive
boolean

Whether to archive (true) or unarchive (false) the invoice. All the invoices must be in 'rejected' or 'completed' status, otherwise the service will return an HTTP 400 with error: 'invalid_invoice_status'

paymentDay
number
Enum: 1 2 3

If set, the updated invoices will change its paymentDueAt date to the next weekday specified in the invoice preferences of the organization. All the invoices must be in 'accepted' status, otherwise the service will return an HTTP 400 with error: 'invalid_invoice_status'. Also, the invoice must belong to an organization, otherwise the service will return an HTTP 400 with error: 'invoice_doesnt_belong_to_an_organization' The organization must had set its invoice preferences, otherwise the service will return an HTTP 400 with error: 'invoice_preferences_not_found' The invoice preferences must have had set the value 'paymentDay' previously, otherwise the service will return an HTTP 400 with error: 'payment_day_not_set'

paymentDueAt
string <date>

When payment is due, in Mexico timezone. All the invoices must be in 'accepted' status, otherwise the service will return an HTTP 400 with error : 'invalid_invoice_status'

isRead
boolean

Responses

Request samples

Content type
application/json
{
  • "invoiceIds": [
    ],
  • "archive": true,
  • "paymentDay": 1,
  • "paymentDueAt": "2025-01-01",
  • "isRead": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Upload invoices zip

Uploads a zip file containing invoices. The zip file must contain XML files.

Authorizations:
OAuth2
query Parameters
provider_id
required
string <uuid>

ID of the provider to upload invoices for

organization_id
string <uuid>

ID of the organization to upload invoices for

Request Body schema: application/json
required
invoicesUploadZipId
required
string <uuid>
createOrganizationProspects
boolean
Default: false
createProducts
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "invoicesUploadZipId": "bbcf8dbf-9e11-41cf-a06b-8a7388f2d310",
  • "createOrganizationProspects": false,
  • "createProducts": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully"
}

Get invoices balance

Retrieves the balance of invoices with optional filters

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXT"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "grossPriceAmount": 1000
}

Stamp an invoice

Stamps an invoice with the provided data using FacturaAPI. Requires provider_id query parameter and valid authentication.

query Parameters
provider_id
required
string

ID of the provider organization that will stamp the invoice

Request Body schema: application/json
required
required
object
required
Array of objects [ 1 .. 5000 ] items
paymentForm
required
string

Payment form code

cfdiUse
required
string

CFDI use code

paymentMethod
required
string

Payment method code

folioNumber
string <= 25 characters

Invoice folio number (optional)

series
string

Invoice series (optional)

Responses

Request samples

Content type
application/json
{
  • "recipient": {
    },
  • "items": [
    ],
  • "paymentForm": "string",
  • "cfdiUse": "string",
  • "paymentMethod": "string",
  • "folioNumber": "string",
  • "series": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "invoice": {
    },
  • "isValid": true,
  • "message": "Invoice created successfully"
}

Get top charts for provider

Retrieves a list of top charts for a provider

Authorizations:
OAuth2
query Parameters
provider_id
required
string <uuid>

ID of the provider to fetch top charts for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get top 5 organizations for provider, or top 5 providers for an organization

Retrieves a list of top 5 organizations for a provider, or top 5 providers for an organization

Authorizations:
OAuth2
query Parameters
provider_id
required
string <uuid>

ID of the provider to fetch top organizations for

organization_id
required
string <uuid>

ID of the organization to fetch top providers for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Batch invoice import

Imports a batch of invoices

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to import invoices for

Request Body schema: application/json
required
fromDate
string <date>
toDate
string <date>
createOrganizationProspects
boolean
createProducts
boolean

Responses

Request samples

Content type
application/json
{
  • "fromDate": "2025-01-01",
  • "toDate": "2025-01-31",
  • "createOrganizationProspects": true,
  • "createProducts": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Get invoice details by ID

Retrieves detailed information about a specific invoice

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "draft",
  • "uuid": "string",
  • "series": "string",
  • "folioNumber": 0,
  • "netPriceAmount": 0,
  • "grossPriceAmount": 0,
  • "discount": 0,
  • "cfdiUse": "string",
  • "paymentMethod": "string",
  • "paymentForm": "string",
  • "issuerName": "string",
  • "issuerTaxIdentifier": "string",
  • "issuerTaxRegime": "string",
  • "issuerTaxRegimes": [
    ],
  • "issuerEconomicActivities": [
    ],
  • "issuerPostalCode": "string",
  • "issuerCountry": "string",
  • "issuerAddressStreet": "string",
  • "issuerAddressNumber": "string",
  • "issuerAddressNumberInterior": "string",
  • "issuerAddressNeighborhood": "string",
  • "issuerAddressCity": "string",
  • "issuerAddressMunicipality": "string",
  • "issuerAddressState": "string",
  • "issuerIsEntity": true,
  • "recipientName": "string",
  • "recipientTaxIdentifier": "string",
  • "recipientTaxRegime": "string",
  • "recipientTaxRegimes": [
    ],
  • "recipientEconomicActivities": [
    ],
  • "recipientPostalCode": "string",
  • "recipientIsEntity": true,
  • "xmlFile": {
    },
  • "pdfFile": {
    },
  • "pdfFileVerifiedAt": "2019-08-24T14:15:22Z",
  • "purchaseOrderFile": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "stampedAt": "2019-08-24T14:15:22Z",
  • "paymentDueAt": "2019-08-24T14:15:22Z",
  • "organization": {
    },
  • "provider": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "localTaxes": [
    ],
  • "payments": [
    ],
  • "invoicePayments": [
    ],
  • "providerProspectId": "string",
  • "isGeneric": true,
  • "confidenceScore": 0,
  • "originalCurrencyCode": "string",
  • "validationErrors": "string",
  • "archivedByOrganizationAt": "2019-08-24T14:15:22Z",
  • "archivedByProviderAt": "2019-08-24T14:15:22Z",
  • "currencyCode": "string",
  • "isCancelled": true,
  • "isDemo": true
}

Update invoice

Updates an invoice

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice to update

Request Body schema: application/json
required
notes
string
isRead
boolean
chartId
string <uuid>
paymentDueAt
string <date>

When payment is due, in Mexico timezone. This value can be updated only if the invoice is in 'accepted' status, otherwise it will return a 400 error (invalid_status)

cfdiUse
string non-empty

CFDI use code. Must be a valid CFDI use. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

paymentForm
string

Payment form code. Must be a valid payment form. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

stampedAt
string <date-time>

Date and time when the invoice was stamped. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

folioNumber
string non-empty

Folio number of the invoice. Must be at least 1 character long. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

series
string non-empty

Series of the invoice. Must be at least 1 character long. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerName
string non-empty

Name of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerTaxIdentifier
string non-empty

Tax identifier (RFC) of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerPostalCode
string non-empty

Postal code of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerCountry
string

Country code of the invoice issuer. Must be a valid country code. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressStreet
string non-empty

Street name of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressNumber
string non-empty

Street number of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressNumberInterior
string non-empty

Interior number of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressNeighborhood
string non-empty

Neighborhood of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressCity
string non-empty

City of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressMunicipality
string non-empty

Municipality of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

issuerAddressState
string

State code of the invoice issuer's address. Must be a valid Mexican state code. Can only be updated if the invoice paymentMethod is 'EXT', otherwise it will return a 400 error (invalid_payment_method).

grossPriceAmount
number > 0

Gross price amount for the invoice. Can only be updated if the invoice paymentMethod is 'EXT' and originalCurrencyCode is 'USD', and status is ACCEPTED, otherwise it will return a 400 error (invalid_payment_method, invalid_currency, or invalid_status).

Responses

Request samples

Content type
application/json
{
  • "notes": "Notas de la factura",
  • "isRead": true,
  • "chartId": "123e4567-e89b-12d3-a456-426614174000",
  • "paymentDueAt": "2025-01-01",
  • "cfdiUse": "G01",
  • "paymentForm": "03",
  • "stampedAt": "2025-01-01T12:00:00Z",
  • "folioNumber": "12345",
  • "series": "A",
  • "issuerName": "Empresa Ejemplo S.A. de C.V.",
  • "issuerTaxIdentifier": "ABC123456XYZ",
  • "issuerPostalCode": "01234",
  • "issuerCountry": "MX",
  • "issuerAddressStreet": "Av. Reforma",
  • "issuerAddressNumber": "123",
  • "issuerAddressNumberInterior": "A",
  • "issuerAddressNeighborhood": "Centro",
  • "issuerAddressCity": "Ciudad de México",
  • "issuerAddressMunicipality": "Miguel Hidalgo",
  • "issuerAddressState": "DF",
  • "grossPriceAmount": 15000.5
}

Response samples

Content type
application/json
{
  • "success": true
}

Download invoice

Downloads a completed invoice. The invoice must be in 'completed' status

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice to download

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pathname": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "downloadUrl": "string",
  • "type": "string",
  • "filename": "string",
  • "url": "string",
  • "status": "processing"
}

Cancel invoice

Cancel an invoice. The invoice must be in 'sent' status and its payment method must be either 'PPD' or 'PUE'

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice to cancel

query Parameters
force
boolean
Example: force=true

If set to true, SAT status won't be checked before setting the invoice as cancelled.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get product keys list from invoices

Retrieves a list of product keys from all invoices of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch product keys for

provider_id
string <uuid>

ID of the provider to fetch product keys for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment forms list from invoices

Retrieves a list of payment forms from all invoices of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch payment forms for

provider_id
string <uuid>

ID of the provider to fetch payment forms for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get payment methods list from invoices

Retrieves a list of payment methods from all invoices of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch payment methods for

provider_id
string <uuid>

ID of the provider to fetch payment methods for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get CFDI uses list from invoices

Retrieves a list of CFDI uses from all invoices of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch CFDI usees for

provider_id
string <uuid>

ID of the provider to fetch CFDI uses for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get entity types list from invoices

Retrieves a list of entity types from all invoices of the organization

query Parameters
organization_id
string <uuid>

ID of the organization to fetch entity types for

provider_id
string <uuid>

ID of the provider to fetch entity types for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download invoices as a zip or xls file

Downloads a zip or xls file containing all selected invoices

Authorizations:
OAuth2
query Parameters
format
required
string
Enum: "zip" "xls"

Format of the file to download

invoice_ids
string

Comma separated list of IDs of the invoices to download. If this parameter is specified, all other query filters (except 'format') will be ignored.

organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXT"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pathname": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "downloadUrl": "string",
  • "type": "string",
  • "filename": "string",
  • "url": "string",
  • "status": "processing"
}

Update multiple invoice statuses

Updates the status of multiple invoices in a single request. The user must have permission to update invoice statuses and be associated with both the provider and organization for each invoice.

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXT"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Request Body schema: application/json
required
invoiceIds
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

IDs of the invoices to update. If this parameter is specified, query filters will be ignored.

status
required
string
Enum: "draft" "sent" "accepted" "paid" "completed" "rejected" "processing" "not_valid"

New status for the invoice

invoicePaymentId
string <uuid>

ID of the invoice payment (required when status is "completed")

Responses

Request samples

Content type
application/json
{
  • "invoiceIds": [
    ],
  • "status": "draft",
  • "invoicePaymentId": "6bd8b670-9f7a-4e56-85e1-a4ae4bb96850"
}

Response samples

Content type
application/json
{
  • "status": [
    ]
}

Upload invoice payment files for an invoice

Uploads XML and PDF invoice payment files for a previously paid invoice. This endpoint validates the uploaded files and creates an invoice payment record.

Authorizations:
OAuth2
query Parameters
invoice_ids
string <uuid>

Comma separated list of IDs of the invoices to attach payment proof files to

Request Body schema: multipart/form-data
required
invoicePaymentXml
required
string <binary>

XML file with payment complement (complemento de pago)

invoicePaymentPdf
string <binary>

PDF file of the payment receipt

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "invoices": [
    ],
  • "message": "Some invoices referenced in the invoice payment were not specified in the request"
}

Invoice Items

Update invoice item

Updates a invoice item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice item to update

Request Body schema: application/json
required
chartId
string or null <uuid>

ID of the chart to assign to the invoice item as receivable invoice. When updating chartId, the chartMode is automatically set: if the previous chartMode was 'reasoning', it will be set to 'reinforcement'; otherwise, it will be set to 'manual'. Set to null to remove the chart assignment.

chartAsPayableId
string or null <uuid>

ID of the chart to assign to the invoice item as payable invoice. When updating chartAsPayableId, the chartAsPayableMode is automatically set: if the previous chartAsPayableMode was 'reasoning', it will be set to 'reinforcement'; otherwise, it will be set to 'manual'. Set to null to remove the chart assignment.

netPriceAmount
number > 0

Net price amount for the invoice item. Can only be updated if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status). When updated, automatically recalculates netUnitPriceAmount, grossPriceAmount, item taxes, invoice taxes, and invoice totals.

quantity
integer >= 1

Quantity for the invoice item. Can only be updated if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status). When updated, automatically recalculates netUnitPriceAmount, grossPriceAmount, item taxes, invoice taxes, and invoice totals.

description
string non-empty

Description of the invoice item. Must be at least 1 character long if provided. Can only be updated if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status).

chartReasoningConfirmed
boolean

Used to mark when a human has confirmed the chart reasoning for the receivable chart.

chartAsPayableReasoningConfirmed
boolean

Used to mark when a human has confirmed the chart reasoning for the payable chart.

Responses

Request samples

Content type
application/json
{
  • "chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
  • "chartAsPayableId": "e5cbc150-426d-4c07-8f16-2678e9338d6e",
  • "netPriceAmount": 1000.5,
  • "quantity": 5,
  • "description": "Product description",
  • "chartReasoningConfirmed": true,
  • "chartAsPayableReasoningConfirmed": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Invoice item updated successfully"
}

Create invoice item tax

Creates a new tax for an invoice item. Can only be created if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED'. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:
OAuth2
Request Body schema: application/json
required
invoiceItemId
required
string <uuid>

ID of the invoice item to add the tax to

taxId
required
string <uuid>

ID of the tax. Must be a valid tax ID.

rate
required
number >= 0

Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the item's netPriceAmount.

Responses

Request samples

Content type
application/json
{
  • "invoiceItemId": "123e4567-e89b-12d3-a456-426614174000",
  • "taxId": "123e4567-e89b-12d3-a456-426614174001",
  • "rate": 0.16
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update invoice item tax

Updates an invoice item tax. Can only be updated if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED'. When rate is updated, automatically recalculates baseAmount and value. When taxId is updated, automatically populates code and isWithholding. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice item tax to update

Request Body schema: application/json
required
taxId
string <uuid>

ID of the tax. Must be a valid tax ID.

rate
number >= 0

Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the item's netPriceAmount.

Responses

Request samples

Content type
application/json
{
  • "taxId": "123e4567-e89b-12d3-a456-426614174001",
  • "rate": 0.16
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete invoice item tax

Deletes an invoice item tax. Can only be deleted if the invoice paymentMethod is 'EXT' and status is 'ACCEPTED'. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the invoice item tax to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Balance

Get balance

Get balance of the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to fetch balance for

Responses

Response samples

Content type
application/json
{
  • "balanceAmount": 0,
  • "lastTransactionAt": "2019-08-24T14:15:22Z"
}

Add balance to organization

Adds balance to an organization. The amount must be at least the minimum balance amount. Requires an organization to have a verified status. If no payment method is specified, the default payment method will be used.

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to add balance to

amount
required
number <decimal>

Amount to add (in MXN). Minimum balance amount required.

payment_method_id
string <uuid>

ID of the payment method to use. If not provided, the default payment method will be used.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Expenses

Get expenses list

Retrieves a paginated list of expenses with optional filters

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

issuer_tax_identifier
string

Filter by issuer tax identifier

issuer_name
string

Filter by issuer name

sort
string
Default: "createdAt"
Enum: "priceAmount" "createdAt" "issuedAt"

Field to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 30
Enum: 10 30 60 100

Number of items per page

minimun_price_amount
number
Example: minimun_price_amount=1000

Filter by minimum price amount

maximun_price_amount
number
Example: maximun_price_amount=2000

Filter by maximum price amount

payment_form
string
Example: payment_form=02,03

Filter by payment form, comma separated

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0,
  • "amount": 0,
  • "unreadCount": 0,
  • "duplicatesCount": 0,
  • "itemCount": 0,
  • "itemsWithChartCount": 0
}

Create a new expense

Creates a new expense by uploading a PDF or image file

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization the expense is for

force_fail
boolean

Force failure analysis of the expense image. If the value is 'true', an empty expense will be created and a failure notification will be sent to the organization.

Request Body schema: multipart/form-data
required
expensePdf
required
string <binary>

PDF version of the expense

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully"
}

Delete multiple expenses

Deletes multiple expenses in a single request. Requires an array of expense IDs in the request body.

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to delete expenses for. Only required when 'duplicates' in request body is true.

Request Body schema: application/json
required
expenseIds
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Array of expense IDs to delete

duplicates
boolean

Whether to delete duplicates

Responses

Request samples

Content type
application/json
{
  • "expenseIds": [
    ],
  • "duplicates": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Update expenses

Updates a list of expenses

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

issuer_tax_identifier
string

Filter by issuer tax identifier

issuer_name
string

Filter by issuer name

sort
string
Default: "createdAt"
Enum: "priceAmount" "createdAt" "issuedAt"

Field to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

minimun_price_amount
number
Example: minimun_price_amount=1000

Filter by minimum price amount

maximun_price_amount
number
Example: maximun_price_amount=2000

Filter by maximum price amount

payment_form
string
Example: payment_form=02,03

Filter by payment form, comma separated

item_description
string
Example: item_description=item description

Filter by item description

Request Body schema: application/json
required
expenseIds
Array of strings <uuid> <= 100 items [ items <uuid > ]

IDs of the epxenses to update. If this parameter is specified, query filters will be ignored.

isRead
boolean

Responses

Request samples

Content type
application/json
{
  • "expenseIds": [
    ],
  • "isRead": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Get expenses balance

Retrieves the balance of expenses for an organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

issuer_tax_identifier
string

Filter by issuer tax identifier

issuer_name
string

Filter by issuer name

minimun_price_amount
number
Example: minimun_price_amount=1000

Filter by minimum price amount

maximun_price_amount
number
Example: maximun_price_amount=2000

Filter by maximum price amount

payment_form
string
Example: payment_form=02,03

Filter by payment form, comma separated

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "priceAmount": 1000
}

Download expenses as a zip or xls file

Downloads a zip or xls file containing all selected expenses

Authorizations:
OAuth2
query Parameters
format
required
string
Enum: "zip" "xls"

Format of the file to download

expense_ids
required
string

Comma separated list of IDs of the expenses to download. If this parameter is specified, all other query filters (except 'format') will be ignored.

organization_id
string <uuid>

ID of the organization to fetch invoices for

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

issuer_tax_identifier
string

Filter by issuer tax identifier

issuer_name
string

Filter by issuer name

sort
string
Default: "createdAt"
Enum: "priceAmount" "createdAt" "issuedAt"

Field to sort by

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

minimun_price_amount
number
Example: minimun_price_amount=1000

Filter by minimum price amount

maximun_price_amount
number
Example: maximun_price_amount=2000

Filter by maximum price amount

payment_form
string
Example: payment_form=02,03

Filter by payment form, comma separated

item_description
string
Example: item_description=item description

Filter by item description

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pathname": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "downloadUrl": "string",
  • "type": "string",
  • "filename": "string",
  • "url": "string",
  • "status": "processing"
}

Upload expenses as a zip file

Uploads a zip file containing expenses

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>
Request Body schema: multipart/form-data
required
expensesUploadZipId
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "File uploaded successfully"
}

Get expense details by ID

Retrieves detailed information about a specific expense

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the expense to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "folioNumber": "string",
  • "barCodeNumber": "string",
  • "priceAmount": 0,
  • "pdfFile": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "organization": {
    },
  • "items": [
    ],
  • "issuerTaxIdentifier": "string",
  • "issuerName": "string",
  • "addressCity": "string",
  • "addressState": "string",
  • "isDemo": true,
  • "isDuplicateOf": {
    },
  • "notes": "string",
  • "confidenceScore": 0,
  • "confidenceScoreDescription": "string",
  • "paymentForm": "string",
  • "paymentFormDescription": "string",
  • "isVerbatim": true,
  • "ratings": [
    ],
  • "classification": "receipt"
}

Update expense

Updates an expense

path Parameters
id
required
string <uuid>

ID of the expense to update

Request Body schema: application/json
required
folioNumber
string
barCodeNumber
string
issuedAt
string <date-time>
issuerName
string
issuerTaxIdentifier
string
addressCity
string
addressState
string
notes
string
paymentForm
string

Payment form code of the expense

priceAmount
number <decimal>

Price amount of the expense

isRead
boolean
isDuplicateOf
string or null

'null' is the only valid value.

Responses

Request samples

Content type
application/json
{
  • "folioNumber": "1234567890",
  • "barCodeNumber": "09876543211234567890",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "issuerName": "Establecimiento",
  • "issuerTaxIdentifier": "RFC12345678XA",
  • "addressCity": "Ciudad de México",
  • "addressState": "México",
  • "notes": "Notas de la factura",
  • "paymentForm": "string",
  • "priceAmount": 0,
  • "isRead": true,
  • "isDuplicateOf": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete expense

Deletes an expense

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the expense to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Rate the expense

Rates the expense details generated by the AI

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the expense to rate

Request Body schema: application/json
required
rating
string
Enum: "positive" "negative" "neutral"

User rating of the expense details generated by the AI

Responses

Request samples

Content type
application/json
{
  • "rating": "positive"
}

Response samples

Content type
application/json
{
  • "success": true
}

Expense Items

Create a new expense item

Creates a new expense item

Request Body schema: application/json
required
expenseId
string <uuid>

ID of the expense to create the item for

description
string

Description of the expense item

quantity
number <decimal>

Quantity of the expense item

unitPriceAmount
number <decimal>

Unit price amount of the expense item

priceAmount
number <decimal>

Price amount of the expense item

discount
number <decimal>

Discount amount of the expense item

chartId
string <uuid>

ID of the chart to assign to the expense item

Responses

Request samples

Content type
application/json
{
  • "expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc",
  • "description": "string",
  • "quantity": 0,
  • "unitPriceAmount": 0,
  • "priceAmount": 0,
  • "discount": 0,
  • "chartId": "54f93a91-b046-4439-9ec5-17949db5a60d"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update expense item

Updates a expense item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the expense item to update

Request Body schema: application/json
required
description
string

Description of the expense item

quantity
number <decimal>

Quantity of the expense item

priceAmount
number <decimal>

Price amount of the expense item

discount
number <decimal>

Discount amount of the expense item

chartId
string or null <uuid>

ID of the chart to assign to the expense item.

chartReasoningConfirmed
boolean

Used to mark when a human has confirmed the chart reasoning.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "quantity": 0,
  • "priceAmount": 0,
  • "discount": 0,
  • "chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
  • "chartReasoningConfirmed": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Expense item updated successfully"
}

Delete expense item

Deletes a expense item

path Parameters
id
required
string <uuid>

ID of the expense item to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Items

List items

Lists all items

Authorizations:
OAuth2
query Parameters
organization_id
required
any

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create item

Creates an item

Request Body schema: application/json
required
description
string

Description of the item

itemKey
string

Item key

unitKey
string

Unit key

netUnitPriceAmount
number <decimal>

Unit price

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "itemKey": "string",
  • "unitKey": "string",
  • "netUnitPriceAmount": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "itemKey": "string",
  • "unitKey": "string",
  • "unitDescription": "string",
  • "netUnitPriceAmount": 0
}

Get item

Gets an item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the item to get

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "itemKey": "string",
  • "unitKey": "string",
  • "unitDescription": "string",
  • "netUnitPriceAmount": 0
}

Update item

Updates an item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the item to update

Request Body schema: application/json
required
description
string

Description of the item

itemKey
string

Item key

unitKey
string

Unit key

netUnitPriceAmount
number <decimal>

Unit price

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "itemKey": "string",
  • "unitKey": "string",
  • "netUnitPriceAmount": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "itemKey": "string",
  • "unitKey": "string",
  • "unitDescription": "string",
  • "netUnitPriceAmount": 0
}

Delete item

Deletes an item

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the item to delete

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Payments

Create a payment

Creates a payment for an invoice. When creating a payment by requesting the CEP, the following information is required:

  • Either paymentTrackingNumber or paymentReferenceNumber must be provided
  • Bank information for both issuer and recipient is required
  • Payment date (paidAt) must be provided in ISO 8601 format (YYYY-MM-DD) and cannot be in the future

When creating a payment by adding a payment proof file, a payment proof file must be attached

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to fetch invoices for

provider_id
string <uuid>

ID of the provider to fetch invoices for

uuid
string <uuid>

Filter by invoice UUID

folio_number
string
Example: folio_number=1234567890

Filter by invoice folio number

series
string
Example: series=S

Filter by invoice series

statuses
string
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

created_at_from
string <date-time>

Filter deductibles created after this date

created_at_to
string <date-time>

Filter deductibles created before this date

issued_at_from
string <date-time>

Filter deductibles issued after this date

issued_at_to
string <date-time>

Filter deductibles issued before this date

stamped_at_from
string <date-time>

Filter deductibles stamped after this date

stamped_at_to
string <date-time>

Filter deductibles stamped before this date

payment_due_at_from
string <date-time>

Filter invoices payment due after this date

payment_due_at_to
string <date-time>

Filter invoices payment due before this date

sent_at_from
string <date-time>

Filter invoices sent after this date

sent_at_to
string <date-time>

Filter invoices sent before this date

created_at_period
string
Example: created_at_period=2025-01

Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_period
string
Example: issued_at_period=2025-01

Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_period
string
Example: stamped_at_period=2025-01

Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.

created_at_current_period
boolean
Default: false

Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

issued_at_current_period
boolean
Default: false

Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

stamped_at_current_period
boolean
Default: false

Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.

archived
boolean
Default: false

Filter by archived status

issuer_name
string
Example: issuer_name=test

Filter by issuer name

recipient_name
string
Example: recipient_name=test

Filter by recipient name

issuer_tax_identifier
string
Example: issuer_tax_identifier=1234567890

Filter by issuer tax identifier

recipient_tax_identifier
string
Example: recipient_tax_identifier=1234567890

Filter by recipient tax identifier

issuer_is_entity
boolean
Default: false

Filter by issuer entity status

recipient_is_entity
boolean
Default: false

Filter by recipient entity status

payment_method
string
Enum: "PPD" "PUE" "EXT"
Example: payment_method=PPD

Filter by payment method

payment_form
string
Example: payment_form=99

Filter by payment form

tax_ids
string
Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz

Filter by tax ids, comma separated

tax_rates
string
Example: tax_rates=0.16

Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.

cfdi_uses
string
Example: cfdi_uses=G03,G04

Filter by cfdi uses, comma separated

minimun_gross_price_amount
number
Example: minimun_gross_price_amount=1000

Filter by minimum gross price amount

maximun_gross_price_amount
number
Example: maximun_gross_price_amount=2000

Filter by maximum gross price amount

item_key
string
Example: item_key=50202310

Filter by item key

item_description
string
Example: item_description=item description

Filter by item description

Request Body schema: application/json
required
invoiceIds
Array of strings <uuid> [ items <uuid > ]
paymentProofFileId
string <uuid>

ID of the payment proof file (only when status is "paid", optional)

paymentTrackingNumber
string

Payment tracking number (either this or paymentReferenceNumber is required when status is "paid")

paymentReferenceNumber
string

Payment reference number (either this or paymentTrackingNumber is required when status is "paid")

paymentIssuerBankId
string

Bank code of the issuing bank (required when status is "paid")

paymentRecipientBankIdentifier
string = 18 characters

CLABE of the receiving bank account (required when status is "paid")

paymentIsOrderingBank
boolean

Whether this is an ordering bank payment (required when status is "paid")

paidAt
string <date>

Date when the payment was made, in Mexico timezone (required when status is "paid", must be in YYYY-MM-DD format and not in the future)

Responses

Request samples

Content type
application/json
{
  • "invoiceIds": [
    ],
  • "paymentProofFileId": "1c3bfd57-07b6-4dab-8d12-b28ae346ad5e",
  • "paymentTrackingNumber": "string",
  • "paymentReferenceNumber": "string",
  • "paymentIssuerBankId": "012",
  • "paymentRecipientBankIdentifier": "012180001234567890",
  • "paymentIsOrderingBank": true,
  • "paidAt": "2024-03-20"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a payment.

Deletes a payment. All invoices associated with the payment will rollback to status 'accepted'. All invoices associated with the payment must be in 'paid' status, otherwise the service will return HTTP 400 with error 'invalid_invoice_status'

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the payment to delete

query Parameters
force
boolean
Default: false

Whether to force delete the payment

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "invoices": [
    ]
}

Payment Proofs

Create a payment proof

Creates a payment proof by analyzing a payment proof file and associating it with one or more invoices. The payment proof file will be processed asynchronously using AI to extract payment information. All invoices must be in 'accepted' status and belong to the same organization and provider (if applicable). The maximum number of invoices per payment proof is 100.

Authorizations:
OAuth2
Request Body schema: application/json
required
paymentProofFileId
required
string <uuid>

ID of the payment proof file to analyze

invoiceIds
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Array of invoice IDs to associate with this payment proof. All invoices must be in 'accepted' status and belong to the same organization and provider.

Responses

Request samples

Content type
application/json
{
  • "paymentProofFileId": "1c3bfd57-07b6-4dab-8d12-b28ae346ad5e",
  • "invoiceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "paymentProof": {
    }
}

Get payment proof details by ID

Retrieves detailed information about a specific payment proof

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

ID of the payment proof to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "issuerBankIdentifier": "string",
  • "recipientBankIdentifier": "string",
  • "beneficiaryName": "string",
  • "paidAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "grossPriceAmount": 0,
  • "issuerBankIdentifierConfidenceScore": 0,
  • "recipientBankIdentifierConfidenceScore": 0,
  • "beneficiaryNameConfidenceScore": 0,
  • "descriptionConfidenceScore": 0,
  • "grossPriceAmountConfidenceScore": 0,
  • "status": "processing"
}

Dashboard

Get income and outcome stats

Retrieves income and outcome stats for the organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to filter statistics for

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD,PUE

Comma-separated list of payment methods to filter by

payment_form
any

Payment form code to filter by

issuer_name
any

Issuer name to filter by

recipient_name
any

Recipient name to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

Responses

Response samples

Content type
application/json
{
  • "totalIncomeGrossPriceAmount": 0,
  • "invoicesReceivableTotalGrossPriceAmountNotGeneric": null,
  • "invoicesReceivableTotalGrossPriceAmountGeneric": null,
  • "invoicesReceivableTotalGrossPriceAmountGenericForeign": null,
  • "totalOutcomeGrossPriceAmount": 0,
  • "invoicesPayableTotalGrossPriceAmount": 0,
  • "deductiblesTotalGrossPriceAmount": 0,
  • "expensesTotalPriceAmount": 0
}

Get top organizations for invoices

Retrieves top organizations from invoices for the organization

Authorizations:
OAuth2
query Parameters
provider_id
string <uuid>

ID of the provider to filter statistics for

organization_id
string <uuid>

ID of the organization to filter statistics for

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD,PUE

Comma-separated list of payment methods to filter by

payment_form
any

Payment form code to filter by

statuses
string
Default: "paid,completed"
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

issuer_name
any

Issuer name to filter by

recipient_name
any

Recipient name to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

payment_due_at_from
string <date>
Example: payment_due_at_from=2024-01-01

Start payment due date for the statistics period (ISO 8601 format)

payment_due_at_to
string <date>
Example: payment_due_at_to=2024-01-31

End payment due date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top items for invoices

Retrieves top items from invoices for the organization

Authorizations:
OAuth2
query Parameters
provider_id
string <uuid>

ID of the provider to filter statistics for

organization_id
string <uuid>

ID of the organization to filter statistics for

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD,PUE

Comma-separated list of payment methods to filter by

payment_form
any

Payment form code to filter by

statuses
string
Default: "paid,completed"
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

description
any

Item description to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

payment_due_at_from
string <date>
Example: payment_due_at_from=2024-01-01

Start payment due date for the statistics period (ISO 8601 format)

payment_due_at_to
string <date>
Example: payment_due_at_to=2024-01-31

End payment due date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalQuantity": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top payment forms for invoices

Retrieves top payment forms from invoices for the organization

Authorizations:
OAuth2
query Parameters
provider_id
string <uuid>

ID of the provider to filter statistics for

organization_id
string <uuid>

ID of the organization to filter statistics for

payment_method
string
Enum: "PPD" "PUE"
Example: payment_method=PPD,PUE

Comma-separated list of payment methods to filter by

payment_form
any

Payment form code to filter by

statuses
string
Default: "paid,completed"
Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid

Comma-separated list of invoice statuses to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

payment_due_at_from
string <date>
Example: payment_due_at_from=2024-01-01

Start payment due date for the statistics period (ISO 8601 format)

payment_due_at_to
string <date>
Example: payment_due_at_to=2024-01-31

End payment due date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top organizations for deductibles

Retrieves top organizations from deductibles for the organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

issuer_name
any

Issuer name to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top items for deductibles

Retrieves top items from deductibles for the organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

description
any

Item description to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalQuantity": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top payment forms for deductibles

Retrieves top payment forms from deductibles for the organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

date_from
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalGrossPriceAmount": 0,
  • "totalInvoicesCount": 0
}

Get top organizations for expenses

Retrieves top organizations from expenses for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

issuer_name
any

Issuer name to filter by

date_from
required
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
required
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalPriceAmount": 0,
  • "totalExpensesCount": 0
}

Get top items for expenses

Retrieves top items from expenses for the organization

Authorizations:
OAuth2
query Parameters
organization_id
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

description
any

Item description to filter by

date_from
required
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
required
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalQuantity": 0,
  • "totalPriceAmount": 0,
  • "totalExpensesCount": 0
}

Get top payment forms for expenses

Retrieves top payment forms from expenses for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to filter statistics for

payment_form
any

Payment form code to filter by

date_from
required
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
required
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

order
string
Default: "desc"
Enum: "asc" "desc"

Sort order

page
integer >= 1
Default: 1

Page number for pagination

limit
integer
Default: 5
Enum: 5 10 30 60 100

Number of items per page

include_totals
any

Whether to include summarized values and page count in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalCount": 0,
  • "totalPages": 0,
  • "totalPriceAmount": 0,
  • "totalExpensesCount": 0
}

Get invoice preferences requirements for an organization

Retrieves invoice preferences requirements for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization

Responses

Response samples

Content type
application/json
{
  • "status": "verified",
  • "isBankingInformationRequired": true,
  • "isComplianceDocumentRequired": true
}

Get charts with amounts

Retrieves charts with amounts for the organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization to filter statistics for

parent_code
any
Example: parent_code=109-02-001

Parent code to filter by

date_from
required
string <date>
Example: date_from=2024-01-01

Start date for the statistics period (ISO 8601 format)

date_to
required
string <date>
Example: date_to=2024-01-31

End date for the statistics period (ISO 8601 format)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get dashboard alerts for an organization

Retrieves dashboard alerts for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string <uuid>

ID of the organization

Responses

Response samples

Content type
application/json
{
  • "pastDuePayableInvoicesCount": 0,
  • "pastDueReceivableInvoicesCount": 0,
  • "sentPayableInvoicesCount": 0,
  • "createdExpensesCount": 0,
  • "createdDeductiblesCount": 0,
  • "paidReceivableInvoicesCount": 0,
  • "completedPayableInvoicesCount": 0,
  • "createdProvidersCount": 0
}

Channels

List Channels

Retrieves a paginated list of channels for a specific organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID to filter channels

page
integer
Default: 1

Page number for pagination

limit
integer
Default: 30

Number of items per page

sort
string
Default: "createdAt"
Enum: "description" "whatsappNumber" "createdAt"

Field to sort by

order
string
Default: "asc"
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "totalPages": 0,
  • "totalCount": 0
}

Create channel

Creates a new channel for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID to create the channel for

Request Body schema: application/json
required
description
required
string

Channel description

whatsappNumber
required
string

WhatsApp phone number

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "whatsappNumber": "1234567890"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "whatsappNumber": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Channel

Retrieves a specific channel by ID

Authorizations:
OAuth2
path Parameters
id
required
string

Channel ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "whatsappNumber": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update Channel

Updates an existing channel

Authorizations:
OAuth2
path Parameters
id
required
string

Channel ID

Request Body schema: application/json
required
description
required
string

Channel description

whatsappNumber
required
string

WhatsApp phone number (without + prefix)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "whatsappNumber": "1234567890"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "whatsappNumber": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete Channel

Deletes a specific channel

Authorizations:
OAuth2
path Parameters
id
required
string

Channel ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Bank Accounts

List Bank Accounts

Retrieves a list of bank accounts for a specific organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID to filter bank accounts

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bank account

Creates a new bank account for an organization

Authorizations:
OAuth2
query Parameters
organization_id
required
string

Organization ID to create the bank account for

Request Body schema: application/json
required
description
required
string

Bank account description

bankIdentifier
required
string

Bank identifier

beneficiaryName
required
string

Beneficiary name

contactFirstName
required
string

Contact first name

contactLastName
required
string

Contact last name

contactEmailAddress
required
string

Contact email address

contactPhoneNumber
required
string

Contact phone number

contactJobTitle
required
string

Contact job title

isDefault
boolean
Default: false

Whether the bank account is the default bank account

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "bankIdentifier": "string",
  • "beneficiaryName": "string",
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactEmailAddress": "string",
  • "contactPhoneNumber": "string",
  • "contactJobTitle": "string",
  • "isDefault": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "bankId": "string",
  • "bankIdentifier": "string",
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactEmailAddress": "string",
  • "contactPhoneNumber": "string",
  • "beneficiaryName": "string",
  • "isDefault": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Bank Account

Retrieves a specific bank account by ID

Authorizations:
OAuth2
path Parameters
id
required
string

Bank account ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "bankId": "string",
  • "bankIdentifier": "string",
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactEmailAddress": "string",
  • "contactPhoneNumber": "string",
  • "beneficiaryName": "string",
  • "isDefault": true,
  • "organizationsOnOrganizations": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update Bank Account

Updates an existing bank account

Authorizations:
OAuth2
path Parameters
id
required
string

Bank account ID

Request Body schema: application/json
required
description
required
string

Bank account description

bankIdentifier
required
string

Bank identifier

beneficiaryName
required
string

Beneficiary name

contactFirstName
required
string

Contact first name

contactLastName
required
string

Contact last name

contactEmailAddress
required
string

Contact email address

contactPhoneNumber
required
string

Contact phone number

contactJobTitle
required
string

Contact job title

isDefault
boolean
Default: false

Whether the bank account is the default bank account

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "bankIdentifier": "string",
  • "beneficiaryName": "string",
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactEmailAddress": "string",
  • "contactPhoneNumber": "string",
  • "contactJobTitle": "string",
  • "isDefault": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "bankId": "string",
  • "bankIdentifier": "string",
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactEmailAddress": "string",
  • "contactPhoneNumber": "string",
  • "beneficiaryName": "string",
  • "isDefault": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete Bank Account

Deletes a specific bank account

Authorizations:
OAuth2
path Parameters
id
required
string

Bank account ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}