Editar una factura en borrador

PUT

/invoices/{id}

curl --request PUT \
  --url https://api.dev.lade.com.mx/invoices/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "teamId": "550e8400-e29b-41d4-a716-446655440000", "items": [ { "description": "Servicio de transporte de carga", "quantity": 1, "price": 10000, "productKey": "78101500", "unitKey": "E48", "taxRate": 0.16 } ], "paymentForm": "03", "paymentMethod": "PUE", "cfdiUse": "G03" }'

• Development environment (dominio custom)
• QA environment
• Production environment
• Development environment (legacy — execute-api URL directo)

Edita una factura en estado DRAFT o ERROR antes de timbrarla: conceptos reales, precios y datos de Carta Porte. El borrador automático creado al registrar el viaje trae valores placeholder (precio 0, concepto genérico); así es como el equipo lo convierte en un CFDI real. Reemplazo completo de items/cartaPorte — el frontend envía el borrador completo editado. Si la factura estaba en ERROR, editarla la regresa a DRAFT.

Authorizations

• cognitoAuth

Parameters

Path Parameters

id

required

string format: uuid

ID de la factura (UUID)

Request Body^required

Media typeapplication/json

object

teamId

required

string format: uuid

items

required

Array<object>

>= 1 items

object

description

required

string

<= 1000 characters

productKey

Clave de producto/servicio SAT (catálogo c_ClaveProdServ)

string

default: 78101500 <= 10 characters

quantity

integer

default: 1 >= 1

unitKey

Clave de unidad SAT (catálogo c_ClaveUnidad)

string

default: E48 <= 10 characters

price

required

number

> 0

taxRate

number

default: 0.16 <= 1

paymentForm

string

default: 03 <= 5 characters

paymentMethod

string

default: PUE

Allowed values: PUE PPD

cfdiUse

string

default: G03 <= 10 characters

notes

string

<= 1000 characters

cartaPorte

Datos del complemento Carta Porte 3.1 que el frontend arma para PUT /invoices/{id}. El backend los combina con los datos del vehículo/conductor del viaje para construir el complemento completo que se envía a Facturapi.

object

totalDistRec

required

Distancia total recorrida en km

number

> 0

origen

required

object

tipoUbicacion

string

Allowed values: Origen Destino

rfc

required

string

<= 13 characters

nombre

required

string

<= 300 characters

fechaHora

required

ISO datetime, ej. 2025-12-18T05:00:00

string

distancia

Km, solo aplica en Destino

number

nullable

domicilio

required

object

calle

string

nullable

codigoPostal

required

string

colonia

Código de 4 dígitos, catálogo SAT

string

nullable

estado

required

Código de 3 letras SAT, ej. NLE, JAL, MEX

string

municipio

string

nullable

pais

string

default: MEX

destino

required

object

tipoUbicacion

string

Allowed values: Origen Destino

rfc

required

string

<= 13 characters

nombre

required

string

<= 300 characters

fechaHora

required

ISO datetime, ej. 2025-12-18T05:00:00

string

distancia

Km, solo aplica en Destino

number

nullable

domicilio

required

object

calle

string

nullable

codigoPostal

required

string

colonia

Código de 4 dígitos, catálogo SAT

string

nullable

estado

required

Código de 3 letras SAT, ej. NLE, JAL, MEX

string

municipio

string

nullable

pais

string

default: MEX

mercancias

required

Array<object>

>= 1 items

object

bienesTransp

required

Clave SAT de bienes transportados

string

descripcion

required

string

cantidad

number

default: 1

claveUnidad

string

default: KGM

pesoKg

required

number

> 0

configVehicular

string

nullable

pesoBrutoVehicular

number

nullable

permSCT

string

nullable

numPermisoSCT

string

nullable

aseguradora

string

nullable

placaRemolque

string

nullable

subtipoRemolque

string

nullable

Example

{
  "teamId": "550e8400-e29b-41d4-a716-446655440000",
  "items": [
    {
      "description": "Servicio de transporte de carga",
      "quantity": 1,
      "price": 10000,
      "productKey": "78101500",
      "unitKey": "E48",
      "taxRate": 0.16
    }
  ],
  "paymentForm": "03",
  "paymentMethod": "PUE",
  "cfdiUse": "G03"
}

Responses

200

Factura actualizada

Media typeapplication/json

object

message

string

invoice

object

id

string format: uuid

teamId

string format: uuid

tripId

string format: uuid

clientId

string

nullable

clientName

string

nullable

facturapiId

string

nullable

folio

string

nullable

series

string

nullable

status

DRAFT: borrador editable (creado automáticamente al crear un viaje). PENDING: timbrado en curso (lock atómico). VALID: timbrada. CANCELLED/CANCELLED_PENDING: cancelada (inmediata o en proceso ante el SAT). ERROR: falló el último intento de timbrado, editable de nuevo.

string

Allowed values: DRAFT PENDING VALID CANCELLED CANCELLED_PENDING ERROR

subtotal

number

taxAmount

number

total

number

paymentForm

Clave SAT c_FormaPago, ej. 03=Transferencia

string

paymentMethod

string

Allowed values: PUE PPD

cfdiUse

Clave SAT c_UsoCFDI, ej. G03=Gastos en general

string

items

Array<object>

object

description

required

string

<= 1000 characters

productKey

Clave de producto/servicio SAT (catálogo c_ClaveProdServ)

string

default: 78101500 <= 10 characters

quantity

integer

default: 1 >= 1

unitKey

Clave de unidad SAT (catálogo c_ClaveUnidad)

string

default: E48 <= 10 characters

price

required

number

> 0

taxRate

number

default: 0.16 <= 1

cartaPorte

Datos del complemento Carta Porte 3.1 que el frontend arma para PUT /invoices/{id}. El backend los combina con los datos del vehículo/conductor del viaje para construir el complemento completo que se envía a Facturapi.

object

totalDistRec

required

Distancia total recorrida en km

number

> 0

origen

required

object

tipoUbicacion

string

Allowed values: Origen Destino

rfc

required

string

<= 13 characters

nombre

required

string

<= 300 characters

fechaHora

required

ISO datetime, ej. 2025-12-18T05:00:00

string

distancia

Km, solo aplica en Destino

number

nullable

domicilio

required

object

calle

string

nullable

codigoPostal

required

string

colonia

Código de 4 dígitos, catálogo SAT

string

nullable

estado

required

Código de 3 letras SAT, ej. NLE, JAL, MEX

string

municipio

string

nullable

pais

string

default: MEX

destino

required

object

tipoUbicacion

string

Allowed values: Origen Destino

rfc

required

string

<= 13 characters

nombre

required

string

<= 300 characters

fechaHora

required

ISO datetime, ej. 2025-12-18T05:00:00

string

distancia

Km, solo aplica en Destino

number

nullable

domicilio

required

object

calle

string

nullable

codigoPostal

required

string

colonia

Código de 4 dígitos, catálogo SAT

string

nullable

estado

required

Código de 3 letras SAT, ej. NLE, JAL, MEX

string

municipio

string

nullable

pais

string

default: MEX

mercancias

required

Array<object>

>= 1 items

object

bienesTransp

required

Clave SAT de bienes transportados

string

descripcion

required

string

cantidad

number

default: 1

claveUnidad

string

default: KGM

pesoKg

required

number

> 0

configVehicular

string

nullable

pesoBrutoVehicular

number

nullable

permSCT

string

nullable

numPermisoSCT

string

nullable

aseguradora

string

nullable

placaRemolque

string

nullable

subtipoRemolque

string

nullable

pdfUrl

string

nullable

xmlUrl

string

nullable

notes

string

nullable

hasCartaPorte

boolean

errorMessage

string

nullable

issuedAt

string format: date-time

createdAt

string format: date-time

updatedAt

string format: date-time

Example

{
  "message": "Invoice updated successfully",
  "invoice": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "status": "DRAFT",
    "subtotal": 10000,
    "taxAmount": 1600,
    "total": 11600
  }
}

400

Solicitud inválida

Media typeapplication/json

object

error

required

string

message

string

field

string

Example

{
  "error": "Validation failed",
  "field": "email",
  "message": "Invalid email format"
}

403

Sin permisos

Media typeapplication/json

object

error

required

string

message

string

field

string

Example

{
  "error": "Forbidden",
  "message": "You don't have permission to access this resource"
}

404

Recurso no encontrado

Media typeapplication/json

object

error

required

string

message

string

field

string

Example

{
  "error": "Not found",
  "message": "Resource not found"
}

502

Error al comunicarse con el proveedor externo (Facturapi/Stripe)

Media typeapplication/json

object

error

required

string

message

string

field

string

Example

{
  "error": "Facturapi error: the CSD certificate is invalid"
}