Receptari

Exemples dels fluxos habituals. Substitueix bk_live_xxx per la teva clau i … pels UUID del tenant. Tots els imports són strings. Si fas servir OAuth2, substitueix bk_live_xxx pel teu access token bo_at_… als mateixos exemples. Consulta Autenticació i scopes.

Comprovar la clau

curl https://api.test.bilteo.com/api/v1/ping \
  -H "Authorization: Bearer bk_live_xxx"
# → { "pong": true }

Descobrir catàlegs

curl "https://api.test.bilteo.com/api/v1/taxes?tax_use=sale&is_active=true" \
  -H "Authorization: Bearer bk_live_xxx"
curl https://api.test.bilteo.com/api/v1/series -H "Authorization: Bearer bk_live_xxx"
curl https://api.test.bilteo.com/api/v1/economic-activities -H "Authorization: Bearer bk_live_xxx"

Si omets sèrie, activitat o moneda, Bilteo aplica els valors per defecte.

Crear i emetre una F1

curl -X POST https://api.test.bilteo.com/api/v1/invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "type": "F1", "partner_id": "…", "operation_date": "2026-01-15",
    "lines": [
      { "description": "Consultoria de gener", "quantity": "10",
        "unit_price": "75.00", "main_tax_id": "…iva21…" }
    ]
  }'

curl -X POST https://api.test.bilteo.com/api/v1/invoices/INV…/actions/issue \
  -H "Authorization: Bearer bk_live_xxx"

La primera petició crea un esborrany; la segona el numera, congela i inicia la remissió a l'AEAT.

F2 simplificada

curl -X POST https://api.test.bilteo.com/api/v1/invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "F2",
        "lines": [{ "description": "Venda de mostrador", "quantity": "1",
                    "unit_price": "30.00", "main_tax_id": "…iva21…" }] }'

Descompte i diversos tipus d'IVA

"lines": [
  { "description": "Servei (21%)", "quantity": "1", "unit_price": "1000.00",
    "discount": "10", "main_tax_id": "…iva21…" },
  { "description": "Llibre (4%)", "quantity": "2", "unit_price": "20.00",
    "main_tax_id": "…iva4…" }
]

Retenció i recàrrec

retention_tax_id resta una retenció del total a pagar; surcharge_tax_id afegeix el recàrrec d'equivalència a la línia.

{ "description": "Servei professional", "quantity": "1", "unit_price": "1000.00",
  "main_tax_id": "…iva21…", "retention_tax_id": "…irpf15…" }

{ "description": "Mercaderia", "quantity": "1", "unit_price": "100.00",
  "main_tax_id": "…iva21…", "surcharge_tax_id": "…re52…" }

Exempta, no subjecta i inversió del subjecte passiu

A l'API pública, la classificació la porta l'impost de main_tax_id:

Operació	type de l'impost
Exempta	exento amb exempt_reason
No subjecta	no_sujeto / no_sujeto_loc
Inversió del subjecte passiu	sujeto_isp

{ "description": "Formació exempta", "quantity": "1", "unit_price": "500.00",
  "main_tax_id": "…exento-art20…" }

Consulta Impostos per al model complet.

Operacions internacionals

Combina el país del client amb l'impost correcte:

Operació	Client	Impost
Entrega intracomunitària de béns	UE amb VAT-IES	exento, art. 25
Serveis B2B intracomunitaris	UE	no_sujeto_loc
Exportació	Fora de la UE	exento, art. 21

curl -X PUT "https://api.test.bilteo.com/api/v1/partners/by-external-id/EU-FR-01" \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "com", "name": "Atelier Vionnet SARL",
        "id_num": "FR47812904563", "country": "FR" }'

Tancar el cicle Veri*Factu

Subscriu-te als webhooks verifactu.accepted i verifactu.rejected. Si necessites consultar:

curl "https://api.test.bilteo.com/api/v1/verifactu-records?invoice_id=INV…" \
  -H "Authorization: Bearer bk_live_xxx"
# pending → in-process → accepted | accepted_error | rejected | unknown_response

Rectificar

curl -X POST https://api.test.bilteo.com/api/v1/invoices/INV…/actions/rectify \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "rectificative_type": "S", "rectification_cause": "law_error" }'

Crea una R1 en esborrany. Consulta el mapatge de causes.

Convertir una F2 en F3

curl -X POST https://api.test.bilteo.com/api/v1/invoices/INV_F2…/actions/replace \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "partner_id": "…" }'

Amb ?issue=true també l'emet a la mateixa crida.

Subsanar un rebuig

Només per corregir un error de remissió. El resultat depèn de l'historial:

curl -X POST https://api.test.bilteo.com/api/v1/invoices/INV…/actions/request-fix \
  -H "Authorization: Bearer bk_live_xxx"
# Mai acceptada (últim registre rejected): needs_fix → corregeix → issue
# Alguna vegada acceptada: continua issued i s'encua la subsanació amb les
#   dades actuals del client (edita-les ABANS amb PATCH /partners/{id})

Consulta el flux complet.

Anul·lar

Només per a una factura emesa per error que no hauria d'haver existit:

curl -X POST https://api.test.bilteo.com/api/v1/invoices/INV…/actions/cancel \
  -H "Authorization: Bearer bk_live_xxx"

Sincronitzar clients i productes

curl -X PUT "https://api.test.bilteo.com/api/v1/partners/by-external-id/CLI-42" \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "com", "name": "Comercial Aldealta SL", "id_num": "B85447761", "country": "ES" }'

curl -X PUT "https://api.test.bilteo.com/api/v1/products/by-external-id/SKU-9" \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "name": "Subscripció anual", "unit_price": "240.00", "main_tax_id": "…iva21…" }'

El PUT retorna 201 en crear i 200 en actualitzar. Consulta Sincronització per external_id.

Descarregar documents

curl "https://api.test.bilteo.com/api/v1/invoices/INV…/actions/print" \
  -H "Authorization: Bearer bk_live_xxx" -H "Accept: application/pdf" -o factura.pdf

curl "https://api.test.bilteo.com/api/v1/invoices/INV…/actions/facturae" \
  -H "Authorization: Bearer bk_live_xxx" -o factura.xml