Ir al contenido
FactuCat Docs

Agregar un concepto

POST
/invoice-drafts/{id}/items
# Guarda tus datos en solicitud.json; consulta los campos debajo.
FACTUCAT_API_URL="${FACTUCAT_API_URL:-https://sandbox.factucat.com/api/v1}"


curl --fail-with-body --request POST \
  --url "$FACTUCAT_API_URL/invoice-drafts/$DOCUMENT_ID/items" \
  --header "X-API-Key: $FACTUCAT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @'solicitud.json'

Authorizations

Sección titulada «Authorizations»

Parameters

Sección titulada «Parameters»

Path Parameters

Sección titulada «Path Parameters»
id
required
string format: uuid

Header Parameters

Sección titulada «Header Parameters»
Idempotency-Key
string
>= 1 characters <= 255 characters

Opcional. Reutiliza la misma clave, ruta y contenido para reintentar una operación sin repetirla. Una clave con contenido diferente devuelve 409. Sin clave, cada solicitud es independiente.

Request Bodyrequired

Sección titulada «Request Bodyrequired»
Media typeapplication/json
object
position
integer
<= 9007199254740991
productCode
string
unitCode
string
description
required
string
>= 1 characters
quantity
number
default: 1 > 0
unitPrice
required
number
vatTreatment

Tratamiento explícito del IVA. Omitido: inferencia automática. vatRate por sí solo conserva el comportamiento anterior; 0 significa Tasa 0%. Si se envían ambos, deben coincidir.

string
Allowed values: iva_16 iva_8 tasa_0 exento no_objeto
vatRate
Any of:
number
0
vatSource
string
Allowed values: manual inferred default
isrWithholdingRate
Any of:
number
0
isrWithholdingSource
string
Allowed values: manual inferred default
suggestedProductCode
string
suggestionConfidence
number
<= 1
suggestionSource
string
Allowed values: ai memory manual review

Responses

Sección titulada «Responses»

200

Sección titulada «200»

Operación exitosa

Media typeapplication/json
object
data
required
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
userId
required
string
>= 1 characters
customerId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
receiverRfc
required
string
receiverLegalName
required
string
receiverPostalCode
required
string
receiverTaxRegime
required
string
receiverFiscalResidence
string
receiverTaxId
string
receiverEmail
string format: email
/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/
receiverInvoiceLanguage
required
string
Allowed values: es en
serie
string
folio
string
satUuid
string
status
required
string
Allowed values: draft issued error cancelled
cfdiType
required
string
cfdiUse
required
string
exportacion
required
string
Allowed values: 01 02 03 04
paymentMethod
string
paymentForm
string
currency
required
string
Allowed values: MXN USD EUR
exchangeRate
required
number
exchangeRateDate
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
subtotal
required
number
vatRate
required
Any of:
number
0
taxTotal
required
number
total
required
number
customerNotes
string
pdfLanguage
required
string
Allowed values: es en
errorMessage
string
issueDate

Fecha de emisión seleccionada, en formato ISO 8601.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
issuedAt
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
cancelledAt
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
createdAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
updatedAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
items
required
Array<object>
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
invoiceId
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
position
required
integer
<= 9007199254740991
productCode
string
unitCode
required
string
description
required
string
quantity
required
number
unitPrice
required
number
amount
required
number
objetoImp
string
Allowed values: 01 02 03 04 05 06 07 08
vatKind
string
Allowed values: none tasa exento
vatTreatment
string
Allowed values: iva_16 iva_8 tasa_0 exento no_objeto
vatRate
required
Any of:
number
0
vatSource
string
Allowed values: manual inferred default
vatReason
string
isrWithholdingRate
required
Any of:
number
0
isrWithholdingSource
string
Allowed values: manual inferred default
isrWithholdingReason
string
suggestedProductCode
string
suggestionConfidence
number
suggestionSource
string
Allowed values: ai memory manual review
meta
required
object
requestId
required
string
>= 1 characters
idempotencyKey
string
>= 1 characters
pagination
object
limit
required
integer
> 0 <= 9007199254740991
offset
required
integer
<= 9007199254740991
hasMore
required
boolean
nextCursor
string | null

400

Sección titulada «400»

Datos inválidos

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

401

Sección titulada «401»

API key ausente, inválida o de otro ambiente

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

403

Sección titulada «403»

Plan inactivo o permisos insuficientes

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

404

Sección titulada «404»

Recurso no encontrado

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

405

Sección titulada «405»

Método no permitido

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

409

Sección titulada «409»

Conflicto o solicitud en curso. error.reason es opcional; duplicate_rfc indica que ya existe un cliente con ese RFC en la cuenta; stamp_in_progress indica que el documento se está timbrando: consúltalo antes de reintentar.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

429

Sección titulada «429»

Límite de solicitudes alcanzado

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

Headers

Sección titulada «Headers»
Retry-After
integer

Segundos antes de reintentar.

500

Sección titulada «500»

Error interno

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string

503

Sección titulada «503»

PAC temporalmente no disponible

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress
message
required
string
>= 1 characters
requestId
required
string
>= 1 characters
retryable
required
boolean
reason
string