BitFactura API
Gracias al API puedes integrar fácilmente BitFactura con otras aplicaciones. El los ejemplos siguientes, usamos CURL: Puedes cambiarla con facilidad a cualquier lenguaje de programación.
Si necesitas algunas funciones adicionales de API, escríbenos y nosotros las añadiremos lo más pronto posible.
Todos ejemplos funcionan también con JSON (simplemente necesita cambiar la extensión del xml al json)
- Facturas
- Productos / servicios
- Clientes
- Documentos de almacén
- Pagos
- Categorías
- Almacenes
- Integraciones
- Departamentos
OJO: Documentación completa está en GitHub
https://github.com/InvoiceOcean/api
OJO: Documentación completa está en GitHub https://github.com/InvoiceOcean/api
Código de API ?
Puedes descargar el código de API de los ajustes de la aplicación (Ajustes -> Ajustes de cuenta -> Integración -> Código de autorización de API)Facturas
Seleccionar todas las facturas de un período seleccionado
seleccionar facturas del mes actual :
JSON
https://YOUR_DOMAIN.bitfactura.com/invoices.json?period=this_month&page=1&per_page=25&api_token=API_TOKEN
XML
https://YOUR_DOMAIN.bitfactura.com/invoices.xml?period=this_month&page=1&per_page=25&api_token=API_TOKEN
Se pueden trasmitir los mismos parámetros que se trasmiten en la aplicación (en la lista de facturas)
Seleccionar factura por identificación
JSON
https://YOUR_DOMAIN.bitfactura.com/invoices/100.json?api_token=API_TOKEN
XML
https://YOUR_DOMAIN.bitfactura.com/invoices/100.xml?api_token=API_TOKEN
Descargar factura en PDF
PDF
https://YOUR_DOMAIN.bitfactura.com/invoices/100.pdf?api_token=API_TOKEN
Enviar factura al cliente por correo electrónico
JSON curl -X POST "https://YOUR_DOMAIN.bitfactura.com/invoices/100/send_by_email.json?api_token=API_TOKEN"
XML curl -X POST "https://YOUR_DOMAIN.bitfactura.com/invoices/100/send_by_email.xml?api_token=API_TOKEN"
Descargar factura en OID
JSON curl "https://YOUR_DOMAIN.bitfactura.com/invoices.json?oid=nr_zam&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/invoices.xml?oid=nr_zam&api_token=API_TOKEN"
Descarga de las facturas por ID de documento que ha sido generado en base de esas facturas.
JSON curl "https://YOUR_DOMAIN.bitfactura.com/invoices.json?invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/invoices.xml?invoice_id=id&api_token=API_TOKEN"
Descarga de las facturas por ID de documento que es la base de esa factura
JSON curl "https://YOUR_DOMAIN.bitfactura.com/invoices.json?from_invoice_id=id&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/invoices.xml?from_invoice_id=id&api_token=API_TOKEN"
Añadir una factura nueva
JSON (recomendado)JSON (recomendado)
curl https://YOUR_DOMAIN.bitfactura.com/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-11-21",
"issue_date": "2024-11-21",
"payment_to": "2024-11-28",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}'
Descargar el código CURLCon datos de departamanto por defecto :
curl https://YOUR_DOMAIN.bitfactura.com/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-11-21",
"issue_date": "2024-11-21",
"payment_to": "2024-11-28",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}'
Descargar el código CURLXML
curl https://YOUR_DOMAIN.bitfactura.com/invoices.xml \
-u 'login:YOUR_PASSWORD' \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-d '<invoice>
<kind>vat</kind>
<sell_date>2024-11-21</sell_date>
<issue_date>2024-11-21</issue_date>
<payment_to>2024-11-28</payment_to>
<seller_name>Seller SA</seller_name>
<seller_tax_no>6272616681</seller_tax_no>
<buyer_name>Client1 SA</buyer_name>
<buyer_tax_no>6272616681</buyer_tax_no>
<positions>
<position>
<name>Produkt X1</name>
<tax>23</tax>
<total_price_gross>20</total_price_gross>
<quantity>1</quantity>
</position>
<position>
<name>Produkt X2</name>
<tax>0</tax>
<total_price_gross>10</total_price_gross>
<quantity>3</quantity>
</position>
</positions>
</invoice>'
Descargar el código CURLEjemplo en Ruby
endpoint = 'https://YOUR_DOMAIN.bitfactura.com/invoices.json'
uri = URI.parse(endpoint)
json_params = {
"api_token" => "API_TOKEN",
"invoice" => {
"kind" =>"vat",
"number" => nil,
"sell_date" => "2024-11-21",
"issue_date" => "2024-11-21",
"payment_to" => "2024-11-28",
"buyer_name" => "Client1 SA",
"buyer_tax_no" => "6272616681",
"positions" =>[
{"name" =>"Produkt A1", "tax" =>23, "total_price_gross" =>10.23, "quantity" =>1},
{"name" =>"Produkt A2", "tax" =>0, "total_price_gross" =>50, "quantity" =>2}
]
}}
request = Net::HTTP::Post.new(uri.path)
request.body = JSON.generate(json_params)
request["Content-Type"] = "application/json"
http = Net::HTTP.new(uri.host, uri.port)
response = http.start {|h| h.request(request)}
if response.code == '201'
ret = JSON.parse(response.body)
else
ret = response.body
end
puts ret.to_json
Javascript / Ajax jQuery
json_params = {
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-11-21",
"issue_date": "2024-11-21",
"payment_to": "2024-11-28",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2}
]
}}
//alert(JSON.stringify(json_params))
endpoint = 'https://YOUR_DOMAIN.bitfactura.com/invoices.json'
$.ajax({
type: "POST",
url: endpoint,
data: json_params,
dataType: 'json',
success: function(data) { alert('invoice created! ' + data['number'])},
});
Añadir factura con descuento en porcentaje
OJO: Antes de expedir el documento, verifica si en ajustes de cuenta en el campo :'Como calcular descuento' has seleccionado 'porcentaje de Precio Unidad'curl https://YOUR_DOMAIN.bitfactura.com/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-11-21",
"issue_date": "2024-11-21",
"payment_to": "2024-11-28",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"show_discount": true,
"discount_kind": "percent_unit",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount_percent": 50},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount_percent": 10}
]
}}'
Descargar el código CURLAñadir factura con cuota de descuento
OJO: Antes de expedir verifica 'Valor' en Ajustes de Cuenta -> Como calcular un descuentocurl https://YOUR_DOMAIN.bitfactura.com/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"invoice": {
"kind":"vat",
"number": null,
"sell_date": "2024-11-21",
"issue_date": "2024-11-21",
"payment_to": "2024-11-28",
"seller_name": "Seller SA",
"seller_tax_no": "6272616681",
"buyer_name": "Client1 SA",
"buyer_tax_no": "6272616681",
"show_discount": true,
"discount_kind": "amount",
"positions":[
{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount": 5},
{"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount": 25}
]
}}'
Descargar el código CURLAñadir factura para un cliente y un producto existentes
Si tienes la identificación del cliente (client_id), del vendedor (department_id) o del producto (product_id) no tienes que rellenar con más datos. La factura se expedirá con la fecha actual y una fecha de vencimiento de 5 días.curl https://YOUR_DOMAIN.bitfactura.com/invoices.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"invoice": {
"payment_to_kind": 5,
"department_id": 222,
"client_id": 111,
"positions":[
{"product_id": 333, "quantity":2}
]
}}'
Descargar el código CURLActualizar factura
curl https://YOUR_DOMAIN.bitfactura.com/invoices/444.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"invoice": {
"buyer_name": "New buyer name SA"
}}'
Descargar el código CURLEliminar factura
JSON curl -X DELETE "https://YOUR_DOMAIN.bitfactura.com/invoices/100.json?api_token=API_TOKEN"
XML curl -X DELETE "https://YOUR_DOMAIN.bitfactura.com/invoices/100.xml?api_token=API_TOKEN"
Documentos de almacén
Todos los documentos de almacén
JSONcurl "https://YOUR_DOMAIN.bitfactura.com/warehouse_documents.json?page=1&per_page=25&api_token=API_TOKEN" Se pueden trasmitir los mismos parámetros que se trasmiten en la aplicación (en la lista de facturas)
Descargar documento seleccionado por ID
JSON curl "https://YOUR_DOMAIN.bitfactura.com/warehouse_documents/555.json?api_token=API_TOKEN"
Nuevo documento de almacén (IM)
JSON
curl https://YOUR_DOMAIN.bitfactura.com/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"pz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-11-21",
"department_name": "Department1 SA",
"client_name": "Client1 SA",
"warehouse_actions":[
{"product_name":"Produkt A1", "purchase_tax":23, "purchase_price_net":10.23, "quantity":1},
{"product_name":"Produkt A2", "purchase_tax":0, "purchase_price_net":50, "quantity":2}
]
}}'
Descargar el código CURLNuevo documento de almacén (SM)
JSON
curl https://YOUR_DOMAIN.bitfactura.com/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"wz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-11-21",
"department_name": "Department1 SA",
"client_name": "Client1 SA",
"warehouse_actions":[
{"product_id":"333", "tax":23, "price_net":10.23, "quantity":1},
{"product_id":"333", "tax":0, "price_net":50, "quantity":2}
]
}}'
Descargar el código CURLAñadir un nuevo documento de almacén para un cliente, departamento y producto existente
Para definir el departamento por defecto, salta las claves department_id y department_nameJSON
curl https://YOUR_DOMAIN.bitfactura.com/warehouse_documents.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse_document": {
"kind":"pz",
"number": null,
"warehouse_id": "1",
"issue_date": "2024-11-21",
"department_id": "222",
"client_id": "111",
"warehouse_actions":[
{"product_id":"333", "purchase_tax":23, "price_net":10.23, "quantity":1},
{"product_id":"333", "purchase_tax":0, "price_net":50, "quantity":2}
]
}}'
Descargar el código CURLActualización del documento
curl https://YOUR_DOMAIN.bitfactura.com/warehouse_documents/555.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"warehouse_document": {
"client_name": "New client name SA"
}}'
Descargar el código CURLEliminar el documento
JSON curl -X DELETE "https://YOUR_DOMAIN.bitfactura.com/warehouse_documents/100.json?api_token=API_TOKEN"
Productos / servicios
Productos
JSON curl "https://YOUR_DOMAIN.bitfactura.com/products.json?page=1&per_page=25&api_token=API_TOKEN&page=1"
XML curl "https://YOUR_DOMAIN.bitfactura.com/products.xml?page=1&per_page=25&api_token=API_TOKEN&page=1"
Seleccionar factura por su identificación
curl "https://YOUR_DOMAIN.bitfactura.com/products/100.xml?api_token=API_TOKEN"
Añadir producto
curl https://YOUR_DOMAIN.bitfactura.com/products.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"product": {
"name": "PoroductAA",
"code": "A001",
"price_net": "100",
"tax": "23"
}}'
Descargar el código CURLActualizar producto
curl https://YOUR_DOMAIN.bitfactura.com/products/333.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"product": {
"name": "PoroductAA2",
"code": "A0012",
"price_gross": "102"
}}'
Descargar el código CURLWidget
Para descargar el widget de pago (en el formato JS) introduce el URL:
https://app.BitFactura.com/a/YOUR_DOMAIN/p/{{token}}.js
Clientes
Clientes
JSON curl "https://YOUR_DOMAIN.bitfactura.com/clients.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/clients.xml?page=1&per_page=25&api_token=API_TOKEN"
Seleccionar cliente usando su identificación
curl "https://YOUR_DOMAIN.bitfactura.com/clients/100.xml?api_token=API_TOKEN"
Seleccionar a un cliente por el ID externo
JSON curl "https://YOUR_DOMAIN.bitfactura.com/clients.json?external_id=100&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/clients.xml?external_id=100&api_token=API_TOKEN"
Añadir un cliente
curl https://YOUR_DOMAIN.bitfactura.com/clients.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"client": {
"name": "Client1",
"tax_no": "6272616681",
"bank" : "bank1",
"bank_account" : "bank_account1",
"city" : "city1",
"country" : "",
"email" : "example@email.com",
"person" : "person1",
"post_code" : "post-code1",
"phone" : "phone1",
"street" : "street1"
}}'
Descargar el código CURLActualizar cliente
curl https://YOUR_DOMAIN.bitfactura.com/clients/111.json \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"api_token": "API_TOKEN",
"client": {
"name": "Klient2",
"tax_no": "62726166812",
"bank" : "bank2",
"bank_account" : "bank_account2",
"city" : "city2",
"country" : "PL",
"email" : "example2@email.com",
"person" : "person2",
"post_code" : "post-code2",
"phone" : "phone2",
"street" : "street2"
}}'
Descargar el código CURLPagos
Todos los pagos
JSON curl "https://YOUR_DOMAIN.bitfactura.com/banking/payments.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/banking/payments.xml?page=1&per_page=25&api_token=API_TOKEN"
Seleccionar pago por su identificación
JSON curl "https://YOUR_DOMAIN.bitfactura.com/banking/payment/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/banking/payments/100.xml?api_token=API_TOKEN"
Añadir un pago nuevo
minimal JSON (recomendado)curl https://YOUR_DOMAIN.bitfactura.com/banking/payments.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"banking_payment": {
"name":"Payment 001",
"price": 100.05,
"invoice_id": null,
"paid":true,
"kind": "api"
}}'
Descargar el código CURLfull JSON (recomendado)
curl https://YOUR_DOMAIN.bitfactura.com/banking/payments.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"banking_payment": {
"city": null,
"client_id":null,
"comment":null,
"country":null,
"currency":"PLN",
"deleted":false,
"department_id":null,
"description":"abonament roczny",
"email":"email@email.pl",
"first_name":"Jan",
"generate_invoice":true,
"invoice_city":"Warszawa",
"invoice_comment":"",
"invoice_country":null,
"invoice_id":null,
"invoice_name":"Company name",
"invoice_post_code":"00-112",
"invoice_street":"street 52",
"invoice_tax_no":"6272616681",
"last_name":"Kowalski",
"name":"Plantnosc za produkt1",
"oid":"",
"paid":true,
"paid_date":null,
"phone":null,
"post_code":null,
"price":"100.00",
"product_id":1,
"promocode":"",
"provider":"transfer",
"provider_response":null,
"provider_status":null,
"provider_title":null,
"quantity":1,
"street":null,
"kind": "api"
}}'
Descargar el código CURLCategorías
Creación de una nueva categoría
JSON (recomendado)curl https://YOUR_DOMAIN.bitfactura.com/categories.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"category": {
"name": "my_category",
"description": null
}
}'
Descargar el código CURLListado de categorías
XML curl "https://YOUR_DOMAIN.bitfactura.com/categories.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.bitfactura.com/categories.json?api_token=API_TOKEN"
Obtener información de una categoría por su ID
XML curl "https://YOUR_DOMAIN.bitfactura.com/categories/100.xml?api_token=API_TOKEN"
JSON curl "https://YOUR_DOMAIN.bitfactura.com/categories/100.json?api_token=API_TOKEN"
Otros ejemplos: https://github.com/InvoiceOcean/api
Almacenes
Crear un almacén
JSON (recomendado)curl https://YOUR_DOMAIN.bitfactura.com/warehouses.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"warehouse": {
"name": "my_warehouse",
"kind": null,
"description": null
}
}'
Descargar el código CURLListado de almacenes
JSON curl "https://YOUR_DOMAIN.bitfactura.com/warehouses.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/warehouses.xml?api_token=API_TOKEN"
Obtener información de un almacén por su ID
JSON curl "https://YOUR_DOMAIN.bitfactura.com/warehouses/100.json?api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.bitfactura.com/warehouses/100.xml?api_token=API_TOKEN"
Integraciones
Añadir nuevo usuario
JSON method: POST url: https://app.bitfactura.com/users.json
{
"user": {
"email": "email58614@fakturowytmail.pl",
"password": "your_secret_password"
},
"integration_token": "email-us-for-this-token"
}
Descargar el código CURL | Descargar el código Ruby | Descargar el código JavaScript | Descargar el código PHP | Descargar el código JSONDescargar datos de usuario (con el código API)
JSON method: POST url: https://app.bitfactura.com/login.json
{
"login": "email58614@fakturowytmail.pl",
"password": "your_secret_password",
"integration_token": "email-us-for-this-token"
}
Descargar el código CURL | Descargar el código Ruby | Descargar el código JavaScript | Descargar el código PHP | Descargar el código JSONCrear cuenta nueva
JSON method: POST url: https://app.bitfactura.com/account.json
{
"api_token": "API_TOKEN",
"account": {
"prefix": "ftprefix"
},
"integration_token": "email-us-for-this-token"
}
Descargar el código CURL | Descargar el código Ruby | Descargar el código JavaScript | Descargar el código PHP | Descargar el código JSONCreación de nueva cuenta junto con el dueño de la cuenta y datos de empresa
JSONcurl https://app.bitfactura.com/account.json \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_token": "API_TOKEN",
"account": {
"prefix": "prefix1"
},
"user": {
"login": "login1",
"email": "email1@email.pl",
"password": "password1",
"from_partner": "PARTNER_CODE"
},
"company": {
"name": "Company1",
"tax_no": "5252445700",
"post_code": "00-112",
"city": "Warsaw",
"street": "Street 1/10",
"person": "Jan Nowak",
"bank": "Bank1",
"bank_account": "111222333444555666111"
},
"integration_token": "email-us-for-this-token"
}'
Descargar el código CURLDescargar datos de usuario
https://YOUR_DOMAIN.bitfactura.com/account.json?api_token=API_TOKEN&integration_token=email-us-for-this-token
Departamentos
Añadir logotipo
curl -X PUT https://YOUR_DOMAIN.bitfactura.com/departments/222.json \
-F 'api_token=API_TOKEN' \
-F 'department[logo]=@/file_path/logo.png'
Descargar el código CURL
Otros ejemplos: https://github.com/InvoiceOcean/api
- Facturas
- Productos / servicios
- Clientes
- Documentos de almacén
- Pagos
- Categorías
- Almacenes
- Integraciones
- Departamentos