Invoice Endpoints

This API provides endpoints to query, create, or delete invoices. An invoice stores detailed information about a sales transaction, including customer data, agent making the sale, products or services sold, and corresponding amounts.

Common characteristics of invoices

Unique identifier: The Invoice entity consists of a unique identifier that serves to distinguish it from other invoices and to easily reference it. It also has an idRemote field, which refers to the id that may be stored in the client's ERP database.
Company: The invoice must be associated with the company that issues the invoice.
Customer: There must be a customer associated with each invoice. The customer is a business partner with the role of Client.
Agent: In addition, an invoice must have an associated agent. This is the representative of the company that made the sale. An agent is a business partner with the role of Representative.
Season: An invoice must also have a Season associated with it. This is used to obtain invoice reports by season.
Discount: An invoice can have discounts associated with it.
Lines: An invoice is made up of lines. Each line on the delivery note corresponds to the product or service requested. The lines store information about the quantity and price of each product or service delivered. The lines have a status that specifies whether it is in stock, whether it is shipped or not, or whether it has been deleted. The lines also include information about the products and possible discounts.

Endpoints

GET/Invoice/getInvoice

Retrieve a paginated list with existing invoices in the database.

Description

Allows you to obtain a list of invoices organized according to pagination parameters:

Parameters

Name	Description	Type	Default Value
`id`	Invoice Id	String optional	id
`page`	Page number	Integer	1
`pageSize`	Number of items per page	Integer	10

Responses

JSON

{
  "data": [
    {
      "id": "string",
      "idRemote": "string",
      "company": {
        "id": "string",
        "idRemote": "string",
        "companyName": "string"
      },
      "client": {
        "id": "string",
        "idRemote": "string",
        "contactName": "string"
      },
      "agent": "string",
      "status": "string",
      "order": {
        "id": "string",
        "idRemote": "string"
      },
      "season": {
        "id": "string",
        "idRemote": "string",
        "description": "string",
        "seasonPos": 0,
        "seasonType": "string",
        "active": true
      },
      "billingAddress": "string",
      "discount": [
        {
          "id": "string",
          "idRemote": "string",
          "discountType": {
            "id": "string",
            "name": "string",
            "code": "string",
            "description": "string"
          },
          "sequence": 0,
          "discount": 0,
          "amountDiscount": 0,
          "isHeader": true
        }
      ],
      "dueDate": [
        {
          "id": "string",
          "idRemote": "string",
          "due_date": 0,
          "amount": 0
        }
      ],
      "lines": [
        {
          "id": "string",
          "idRemote": "string",
          "lineStatus": "string",
          "discount": [
            {
              "id": "string",
              "idRemote": "string",
              "discount": 0,
              "amountDiscount": 0
            }
          ],
          "observations": "string",
          "deliveryDate": "string",
          "cancellationDate": "string",
          "lineAmount": 0,
          "quantity": 0,
          "lineDetail": [
            {
              "productId": "string",
              "quantity": 0,
              "price": 0
            }
          ]
        }
      ],
      "invoiceDate": "string",
      "valueDate": "string",
      "grossAmount": 0,
      "baseAmount": 0,
      "shippingAmount": 0,
      "taxAmount": 0,
      "taxrecAmount": 0,
      "totalAmount": 0,
      "totalQuantity": 0,
      "totalWeight": 0,
      "totalPacks": 0,
      "baseCommission": 0,
      "percentCommission": 0,
      "totalCommission": 0,
      "invoicePaid": true,
      "invoiceSettled": true,
      "pendingAmount": 0,
      "unpaidAmount": 0,
      "paymentDate": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "pagination": {
    "totalItems": 0,
    "itemsPerPage": 0,
    "currentPage": 0,
    "totalPages": 0,
    "nextPageUrl": "string"
  }
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<export>
  <data>
    <item>
      <id>string</id>
      <idRemote>string</idRemote>
      <company>
        <id>string</id>
        <idRemote>string</idRemote>
        <companyName>string</companyName>
      </company>
      <client>
        <id>string</id>
        <idRemote>string</idRemote>
        <contactName>string</contactName>
      </client>
      <agent>string</agent>
      <status>string</status>
      <order>
        <id>string</id>
        <idRemote>string</idRemote>
      </order>
      <season>
        <id>string</id>
        <idRemote>string</idRemote>
        <description>string</description>
        <seasonPos>0</seasonPos>
        <seasonType>string</seasonType>
        <active>true</active>
      </season>
      <billingAddress>string</billingAddress>
      <discount>
        <id>string</id>
        <idRemote>string</idRemote>
        <discountType>
          <id>string</id>
          <name>string</name>
          <code>string</code>
          <description>string</description>
        </discountType>
        <sequence>0</sequence>
        <discount>0</discount>
        <amountDiscount>0</amountDiscount>
        <isHeader>true</isHeader>
      </discount>
      <dueDate>
        <id>string</id>
        <idRemote>string</idRemote>
        <due_date>0</due_date>
        <amount>0</amount>
      </dueDate>
      <lines>
        <id>string</id>
        <idRemote>string</idRemote>
        <lineStatus>string</lineStatus>
        <discount>
          <id>string</id>
          <idRemote>string</idRemote>
          <discount>0</discount>
          <amountDiscount>0</amountDiscount>
        </discount>
        <observations>string</observations>
        <deliveryDate>string</deliveryDate>
        <cancellationDate>string</cancellationDate>
        <lineAmount>0</lineAmount>
        <quantity>0</quantity>
        <lineDetail>
          <productId>string</productId>
          <quantity>0</quantity>
          <price>0</price>
        </lineDetail>
      </lines>
      <invoiceDate>string</invoiceDate>
      <valueDate>string</valueDate>
      <grossAmount>0</grossAmount>
      <baseAmount>0</baseAmount>
      <shippingAmount>0</shippingAmount>
      <taxAmount>0</taxAmount>
      <taxrecAmount>0</taxrecAmount>
      <totalAmount>0</totalAmount>
      <totalQuantity>0</totalQuantity>
      <totalWeight>0</totalWeight>
      <totalPacks>0</totalPacks>
      <baseCommission>0</baseCommission>
      <percentCommission>0</percentCommission>
      <totalCommission>0</totalCommission>
      <invoicePaid>true</invoicePaid>
      <invoiceSettled>true</invoiceSettled>
      <pendingAmount>0</pendingAmount>
      <unpaidAmount>0</unpaidAmount>
      <paymentDate>string</paymentDate>
      <createdAt>string</createdAt>
      <updatedAt>string</updatedAt>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Try it out🌱

GET/Invoice/getInvoice/Status

Retrieves a paginated list with the identifiers and description of the available statuses for the invoices.

Description

Local and remote identifiers are displayed in a paginated manner along with the status description. Pagination can be modified through these parameters:

Parameters

Name	Description	Type	Default Value
`page`	Page number	Integer	1
`pageSize`	Number of items per page	Integer	10

Responses

JSON

  {
    "data": [
        {
        "id": "string",
        "value": true
        }
    ],
    "pagination": {
        "totalItems": 0,
        "itemsPerPage": 0,
        "currentPage": 0,
        "totalPages": 0,
        "nextPageUrl": "string"
    }
  }

XML

<?xml version="1.0" encoding="UTF-8"?>
<export>
  <data>
    <item>
      <id>string</id>
      <value>true</value>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Try it out🌱

GET/Invoice/getInvoice/Line/Status

Retrieve a paginated list with the identifiers and descriptions of the available statuses for invoice lines.

Description

Local and remote identifiers are displayed in a paginated manner along with the status description. Pagination can be modified using these parameters:

Parameters

Name	Description	Type	Default Value
`page`	Page number	Integer	1
`pageSize`	Number of items per page	Integer	10

Responses

JSON

  {
    "data": [
        {
        "id": "string",
        "idRemote": "string",
        "description": true
        }
    ],
    "pagination": {
        "totalItems": 0,
        "itemsPerPage": 0,
        "currentPage": 0,
        "totalPages": 0,
        "nextPageUrl": "string"
    }
  }

XML

<?xml version="1.0" encoding="UTF-8"?>
<export>
  <data>
    <item>
      <id>string</id>
      <idRemote>string</idRemote>
      <description>true</description>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Try it out🌱

POST/Invoice/create

Factors to consider

When creating a new invoice, you must take into account the following factors:

Company: Before registering an invoice, make sure that the Company you are going to assign to it exists. If the assigned company does not exist, the response will return an error. For more information on how to create a Company, follow this link: 👉Create a Company🌱
Customer Business Partner: Make sure that the Business Partner you are going to assign to the invoice in the clientId parameter has the Client role and belongs to the same Company as the invoice issuer. If you attach an incorrect Customer Business Partner, the response will return an error. For more information on how to create a Business Partner follow this link: 👉Create a Business Partner🌱
Business Partner Agent: It is crucial that you make sure that the Business Partner you are going to assign to the invoice in the agentId parameter has the Representative role and belongs to the same Company as the Invoice issuer. If you attach the wrong agent, the response will return an error. For more information on how to create a Business Partner follow this link: 👉Create a Business Partner🌱
Order: It is necessary to make sure that the Order you are going to associate to the Invoice through the orderId parameter is registered in the system. Also, the order to be associated with the new record must belong to the same Company and Season as the Invoice you want to create. Otherwise the response will return an exception. For more information about creating Orders follow the link below: 👉Create an Order🌱
Season: You must attach a correct reference to a Season through the seasonId parameter. You can find information on how to get existing Seasons, or how to register a new Season in the system through this link: 👉Create a Season🌱
Invoice Status: The reference to the Invoice Status must exist in the system. To see the available statuses for Invoices you can use the endpoint described above in this documentation.
Billing Address You must attach the billing address when creating a new invoice. This field is an id that references a Location entity. You must attach an existing id in the system, which also belongs to the Business Partner to whom the invoice is addressed. In addition, the Location that corresponds to the billing address must have the billingAddress field set to true. Locations can be configured through the Locations endpoints or when creating a new Business Partner. 👉Business Partner Creation🌱 👉Endpoints for Locations🌱
Discounts: Discounts are not a mandatory parameter. To enter an invoice without discounts into the system, simply attach an empty array. You can set an idRemote for each discount. The system will automatically create a local id for each new discount you create this way.
Due Date: Due dates can be set for invoices. The date must be entered in a valid format. For example: 2024-10-10 01:01:01.
Lines: An invoice is made up of lines. The lines are related to the product being sold through the lineDetails field, in which an existing Product in the system must be attached. In addition, each line is related to a Status (lineStatusId) and a Delivery Note (deliveryNoteId). By creating lines, you can assign an idRemote to each one. The system will automatically create a local id. You can also associate discounts with each line of the Delivery Note. The process of creating discounts for each line corresponds to the process of creating discounts for an invoice described above.

Mandatory Parameters

Name	Description	Type
`idRemote`	Identifier of the new Invoice	String
`reference`	Reference of the new Invoice	String
`companyId`	Identifier of the Company to which the new Invoice belongs	String
`clientId`	Identifier of the Business Partner with the client role	String
`agentId`	Identifier of the Business Partner with the agent role	String
`orderId`	Identifier of the Order associated with the new Invoice	String
`billingAddressId`	Identifier of the Billing Location for the Invoice	String
`invoiceStatusId`	Identifier of the Invoice status	String
`lines`	Lines that make up the Invoice. They contain detailed information about it	Array
`invoiceDate`	Invoice issue date. Must be in the format `2024-10-10 01:01:01`	String
`valueDate`	Must be in the format `2024-10-10 01:01:01`	String
`grossAmount`	Gross amount of the Invoice	Decimal
`baseAmount`	Base amount of the Invoice	Decimal
`shippingAmount`	Shipping costs of the Invoice	Decimal
`taxAmount`	Tax amount of the Invoice	Decimal
`taxrecAmount`		Decimal
`totalAmount`	Total amount of the Invoice	Decimal
`totalQuantity`	Total quantity of products in the Invoice	Decimal
`totalWeight`	Total weight of the packages to be invoiced	Decimal
`totalPacks`	Total number of packages to be invoiced	Decimal
`baseCommission`	Base commission	Decimal
`percentCommission`	Commission percentage	Decimal
`totalCommission`	Total commission	Decimal
`invoicePaid`	Indicates whether the Invoice is paid or not	Boolean
`invoiceSettled`	Indicates whether the Invoice has been settled or not	Boolean
`pendingAmount`	Pending payment amount of the Invoice	Decimal
`unpaidAmount`	Unpaid amount of the Invoice	Decimal

Mandatory Parameters in Lines

The program is designed to initialize some attributes if no values are attached for them. You can associate lines with a Delivery Note to relate the Invoice to a Delivery Note.

Name	Description	Type
`lineStatusId`	Invoice Line Status Identifier	String

Lines can contain Discounts and Line Details.

All attributes of the Line Detail are optional, except for the productId

The complete body of a request to create an Invoice must follow the following scheme:

[
  {
      "idRemote": "string",
      "companyId": "string",
      "clientId": "string",
      "agentId": "string",
      "orderId": "string",
      "seasonId": "string",
      "invoiceStatusId": "string",
      "billingAddressId": "string",
      "reference": "string",
      "discount": [
      {
          "idRemote": "string",
          "discountType": "string",
          "sequence": 0,
          "discount": 0,
          "amountDiscount": 0,
          "isHeader": true
      }
      ],
      "dueDate": [
      {
          "idRemote": "string",
          "due_date": 0,
          "amount": 0
      }
      ],
      "lines": [
        {
          "idRemote": "string",
          "lineStatusId": "string",
          "deliveryNoteId": "string",
          "discount": [
            {
              "idRemote": "string",
              "discount": 0,
              "amountDiscount": 0
            }
          ],
          "observations": "string",
          "deliveryDate": "string",
          "cancellationDate": "string",
          "lineAmount": 0,
          "quantity": 0,
          "lineDetail": [
            {
              "productId": "string",
              "quantity": 0,
              "price": 0
            }
          ]
        }
      ],
      "invoiceDate": "string",
      "valueDate": "string",
      "grossAmount": 0,
      "baseAmount": 0,
      "shippingAmount": 0,
      "taxAmount": 0,
      "taxrecAmount": 0,
      "totalAmount": 0,
      "totalQuantity": 0,
      "totalWeight": 0,
      "totalPacks": 0,
      "shipper": "string",
      "baseCommission": 0,
      "precentCommission": 0,
      "totalCommission": 0,
      "invoicePaid": true,
      "invoiceSettled": true,
      "pendingAmount": 0,
      "unpaidAmount": 0,
      "paymentDate": "string"
  }
]

It is possible to add multiple invoices through the same request by separating them with commas within the array in the body of the request.

Responses

In order not to saturate the server, this endpoint sends a message to a consumer in charge of processing the request. To check the status of the request sent, it is necessary to access the URL attached to the response. A response correctly sent to the consumer should look like this:

{
    "code": 201,
    "message": "Invoice message created successfully and dispatched to the queue.",
    "statusUrl": "http://host/api/database/v1/message/status/messageId"
}  

The statusUrl field redirects us to a more detailed response about the status of the request. A request successfully processed by the consumer looks like this:

{
  "data": [
      {
        "status": "completed",
        "errorMessage": null
      }
    ],
      "pagination": {
      "totalItems": 1,
      "itemsPerPage": 10,
      "currentPage": 1,
      "totalPages": 1,
      "nextPageUrl": null
    }
}

If any error occurs during message processing, the response will look something like this:

{
  "code": 400,
  "error": "Invalid invoice data format, a required parameter is missing"
}

👉Try it out🌱

DELETEInvoice/delete/{id}

Delete an existing invoice.

Description

Deletes an invoice from the database using the identifier provided in the parameters. This id field can be either the identifier generated by the B2B database or the idRemote you provide when registering invoices. Deleting an Invoice removes all associated lines, discounts, and due dates. Once deleted, the Invoice is recorded in the Deleted History.

⚠️An Invoice that has lines associated with a Delivery Note cannot be deleted.

Parameters

Name	Description	Type
`id`	Invoice identifier	String required

👉Try it out🌱

Possible Response Errors

Error	Response Status	Response Body
This error occurs when a connection to the database cannot be established. It is an internal server problem.	500	`{"code": 500,"error": "Database connection failed."}`
This error occurs when you cannot insert or update into the database.	500	`{"code": 500,"error": "Invalid connection name, you cannot insert in default"}`
This error indicates that a parameter is missing.	400	`{"code": 400,"error": "Parameter $parameter is required"}`
This error occurs when you are not authorized.	401	`{"code": 401,"error": "Unauthorized."}`
This error indicates that the entity could not be found.	404	`{"code": 404,"error": "No entity found for Invoice with $id."}`
This error occurs when you try to insert an entity that already exists.	409	`{"code": 409,"error": "Duplicate entry => Care with email and username"}`
This error occurs when you try to send too many requests in a short period of time.	429	`{"code": 429,"error": "Too Many Requests"}`

Invoice Endpoints

Common characteristics of invoices​

Endpoints​

GET/Invoice/getInvoice​

Description​

Parameters​

Responses​

JSON​

XML​

GET/Invoice/getInvoice/Status​

Description​

Parameters​

Responses​

JSON​

XML​

GET/Invoice/getInvoice/Line/Status​

Description​

Parameters​

Responses​

JSON​

XML​

POST/Invoice/create​

Factors to consider​

Mandatory Parameters​

Mandatory Parameters in Lines​

Responses​

DELETEInvoice/delete/{id}​

Description​

Parameters​

Possible Response Errors​

Common characteristics of invoices

Endpoints

GET/Invoice/getInvoice

Description

Parameters

Responses

JSON

XML

GET/Invoice/getInvoice/Status

Description

Parameters

Responses

JSON

XML

GET/Invoice/getInvoice/Line/Status

Description

Parameters

Responses

JSON

XML

POST/Invoice/create

Factors to consider

Mandatory Parameters

Mandatory Parameters in Lines

Responses

DELETEInvoice/delete/{id}

Description

Parameters

Possible Response Errors