Sovos.com Contact Support

e-invoicing

Compliance Network Implementation Guide

Costa Rica

Enabling support for Costa Rica involves obtaining a Registro Único Tributario (RUT), Administración Tributaria Virtual (ATV) credentials, and a valid digital certificate or cryptographic key.

Prerequisites

  • A RUT (tax ID), username and password, obtained from the ATV

  • A valid digital certificate or cryptographic key to electronically sign documents

Buyer acceptance or rejection

If the buyer or recipient of the invoice is an issuer or authorized recipient of electronic invoices, they must accept, or (partially) reject the invoice by sending a message in XML format to the Ministerio de Hacienda.

Note: Sovos does not support sending and receiving buyer acceptance or rejection messages.

Available products

  • cr_fex__4.3

  • cr_fec__4.3

  • cr_fe__4.3

  • cr_nce_4.3

  • cr_te__4.3

  • cr_nde__4.3

Error handling

When handling errors, the client application must follow the Indirect Tax API's error handling principles, as specified in the error handling documentation.

In general, all error codes in the 400 range are client errors, which you need to analyze. After fixing the error, you can resend the request. Error codes 408 and 429 are exceptions: In these cases, you should wait at least 60 seconds before retrying. Error codes in the 500 range are server errors. In that case, resend the request according to the instructions given on the error handling documentation, which also includes a full list of error codes Indirect Tax API can return.

Errors coming from the tax authority are shown in the application response. This means that if the tax authority rejects the request, SCIResponseCode is set to "RE" and any error codes will be located in the SCIGovtStatusCode element.

Note:

You need to take action after receiving an error code and a message from the tax authority.

Issue invoice

Issuing an invoice in Costa Rica is based on the Default business process, which follows this order: Mapping, Signing, Transmission, and Distribution. The following diagram provides a detailed overview of the process:

Costa Rica outbound flow

Step 1: Supplier creates the Standard Business Document

Every transactional document sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Here are some key elements that should be included in the SBD:

SCI invoiceSCI credit noteSCI debit noteSCI ticket

Use the following values in the SBDH for invoice documents that use the SCI format:

Node Required Attributes Value
StandardBusinessDocumentHeader.Sender.Identifier Yes Authority="CR" Supplier's tax ID
StandardBusinessDocumentHeader.Receiver.Identifier Yes Authority="CR"
StandardBusinessDocumentHeader.DocumentIdentification.Standard Yes urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion Yes 2.1
StandardBusinessDocumentHeader.DocumentIdentification.Type Yes Invoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Country

Child node Identifier: CR
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: ProcessType

Child node Identifier: Outbound
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: CompanyCode

Child node Identifier : Supplier's tax ID
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: SenderDocumentId

Child node Identifier: A unique document ID. We recommend the ERP document ID.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: SenderSystemId

Child node Identifier: The system ID configured in the backend. This parameter is used to determine which notifications are returned to the client and what attachments they include. If SenderSystemId is not configured on the client side, it will use the default value of "DefaultSystemERP". For more information, see this topic.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.OutputSchema

Child node Identifier : FacturaElectronica
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.TransformDocument

Child node Identifier: SCI-TO-LEGAL_INVOICE
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) No

Child node Type: BusinessCategory

Child node Identifier: Child node Identifier: BusinessToBusiness or BusinessToConsumer. The default mode is BusinessToBusiness when this node is omitted, so if the transaction is business to consumer, this must be explicitly specified.
StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName Yes Default
SovosDocument.SovosCanonicalInvoice.Invoice Yes SCI

In case you want to send a credit note, make these changes in the SBDH:

Node Required Value
StandardBusinessDocumentHeader.DocumentIdentification.Standard Yes urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2
StandardBusinessDocumentHeader.DocumentIdentification.Type Yes CreditNote
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.OutputSchema

Child node Identifier : NotaCreditoElectronica
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.TransformDocument

Child node Identifier : SCI-TO-LEGAL_CREDIT_NOTE

In case you want to send a debit note, make these changes in the SBDH:

Node Required Value
StandardBusinessDocumentHeader.DocumentIdentification.Standard Yes urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2
StandardBusinessDocumentHeader.DocumentIdentification.Type Yes DebitNote
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.OutputSchema

Child node Identifier : NotaDebitoElectronica
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.TransformDocument

Child node Identifier : SCI-TO-LEGAL_DEBIT_NOTE

In case you want to send a ticket document, make these changes in the SBDH:

Node Required Value
StandardBusinessDocumentHeader.DocumentIdentification.Standard Yes urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
StandardBusinessDocumentHeader.DocumentIdentification.Type Yes TiqueteElectronico
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.OutputSchema

Child node Identifier : TiqueteElectronico
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) Yes

Child node Type: Mapping.TransformDocument

Child node Identifier : SCI-TO-LEGAL_TICKET
Note:

Include all the mandatory nodes, as specified in the SBDH schema. If the information cannot be provided, and the respective mandatory node has not been mentioned on the current page, for example the receiver.identifier, the node can be left empty but must still be included in the SBDH.

SBD sample
Below is a sample of the SBD. In addition, there's a full sample of the SBD on the Postman Samples page.
CODE 
<sbd:StandardBusinessDocument xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="CR">99999999999</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="CR"/>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Receiver>
		<sbd:DocumentIdentification>
			<sbd:Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</sbd:Standard>
			<sbd:TypeVersion>2.1</sbd:TypeVersion>
			<sbd:InstanceIdentifier/>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2020-10-01T00:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>CR</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.OutputSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>FacturaElectronica</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>99999999999</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>12345</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UAT101</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessProcess</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:BusinessService>
					<sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
				</sbd:BusinessService>
			</sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
                *UBL Nodes*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint.

The request must include the following request body parameters:

Name Type Required Description
data string Yes The Base64-encoded SBD from step 1
dataEncoding string Yes Use "base64"
Request sample
JSON 
curl --location --request POST 'https://api-test.sovos.com/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'
Response sample
JSON 
{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf"
    }
}

Step 3: Sovos maps the SCI into XML

Upon receiving the SCI, Sovos maps the file into the required XML format.

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the XML file contains the necessary information.

Step 5: Sovos signs the XML

Sovos signs the XML with the supplier's digital certificate or cryptographic key.

Step 6: Sovos transmits the XML

Sovos transmits the signed XML file to to the tax authority for clearance.

Step 7: Tax authority processes the XML

The tax authority performs the clearance process, which includes a schema validation, business validations, and a signature validation. They also generate an acceptance or rejection message (comprobante).

After the process is complete, the tax authority returns the message to Sovos.

Step 8: Sovos generates the PDF

Sovos generates a PDF file that includes the content of the cleared XML based on the configured PDF template.

Step 9: Sovos distributes the PDF and the XML

As explained in step 11, the supplier can retrieve the XML including the comprobante and the PDF through a GET API request. But Sovos can also distribute the PDF and the XML. Available options:

  • Email

  • AS2

  • SFTP

  • Web services

Note:

The delivery method must be preconfigured. Otherwise, this step will be skipped.

Step 10: Storing

Sovos stores the PDF and the XML.

Step 11: Supplier retrieves the application responses

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and a URL to access the cleared XML including the comprobante and the PDF after they're available during the process.

To complete a transaction, the supplier must retrieve application responses until the SCIResponseCode in the response has the value of either "AP" or "RE", which indicates that the transaction is finished.

The supplier can use the following Indirect Tax API endpoints to retrieve application responses:

  • GET /notifications/CR

  • GET /documents/CR/{documentId}/notifications

GET /notifications/CR
The supplier can send a GET request to the /notifications/CR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:
Name Type Required Default Description
taxId string No Include only notifications related to the specified taxId. This value is related to the CompanyCode in the SBDH.
page integer No 1 To specify the page to be returned, use a value between 1 and 10.
perPage integer No 10

To specify the number of results for the returned page, use a value between 1 and 100.

Important:

If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId string Yes Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged boolean No false Use "true" to include previously acknowledged notifications in the result.
includeBinaryData boolean No false Use "true" to include the binary data of the XML and PDF in the application response.
processType string No Use "0" to only include notifications related to outbound documents.
Request sample
JSON 
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/CR?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&includeBinaryData=true&processType=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'
Response sample
JSON 
{
    "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "FE",
                    "documentId": "3428ba6600dfd042a2090390e04471ed16b1",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": 1629857132,
                "metadata": {
                    "productId": "FE",
                    "documentId": "3b20cf820153a0407f0b40402482b216cd7b",
                    "erpDocumentId": "321412",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "102",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "6b0e273b-9ba9-43bc-9911-7eea7867786e",
                "content": "PEF...NlPg=="
            }
        ]
    }
}
GET /documents/CR/{documentId}/notifications
The supplier can send a GET request to the /documents/CR/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following parameters:
Name Type Required Parameter type Default Description
documentId string Yes Path The document ID returned in step 2
includeAcknowledged boolean No Query false Use "true" to include previously acknowledged notifications in the result
includeBinaryData boolean No Query false Use "true" to include the binary data of the XML and PDF in the application response
Request sample
JSON 
curl --location --request GET 'https://api-test.sovos.com/v1/documents/CR/{documentId}/notifications?includeAcknowledged=true&includeBinaryData=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'
Response sample
JSON 
{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "FE",
                    "documentId": "0af1d17c-759a-4b93-b6f5-ad11601be390",
                    "erpDocumentId": "76059264",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "INV",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 12: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/CR endpoint.

To make this request, set the following request body parameters:

Name Type Required Description
status string Yes Use "read"
notificationId string Yes The notification ID
Note: Multiple notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.
Request sample
JSON 
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/CR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76"
    }
]'
Response sample
JSON 
{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Step 13: Supplier sends the XML and the PDF to the Buyer

As the final step, the supplier should send the XML and the PDF to the buyer through an agreed-upon channel.

Note:

This process is outside the scope of Sovos

In case the buyer is an electronic issuer or an authorized recipient of electronic invoices, they must accept or partially reject the invoice by sending a message to the tax authority. Sovos does not support the issuance or reception of acceptance and rejection messages.

Costa Rica Compliance Network Public Implementation Current

Last updated: October 1, 2026