Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers?status=accepted%2Crejected&voucher_type=01%2C04&date_from=2026-04-01&date_to=2026-04-30&receiver_id_number=3101234567&environment=production&currency_code=CRC&contributor_id=019d867d-c001-7288-8ece-fd64da756c01&sort_by=issued_at&sort_dir=desc&per_page=15&page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers"
);

const params = {
    "status": "accepted,rejected",
    "voucher_type": "01,04",
    "date_from": "2026-04-01",
    "date_to": "2026-04-30",
    "receiver_id_number": "3101234567",
    "environment": "production",
    "currency_code": "CRC",
    "contributor_id": "019d867d-c001-7288-8ece-fd64da756c01",
    "sort_by": "issued_at",
    "sort_dir": "desc",
    "per_page": "15",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'status' => 'accepted,rejected',
            'voucher_type' => '01,04',
            'date_from' => '2026-04-01',
            'date_to' => '2026-04-30',
            'receiver_id_number' => '3101234567',
            'environment' => 'production',
            'currency_code' => 'CRC',
            'contributor_id' => '019d867d-c001-7288-8ece-fd64da756c01',
            'sort_by' => 'issued_at',
            'sort_dir' => 'desc',
            'per_page' => '15',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listado paginado):

{
    "success": true,
    "data": [
        {
            "voucher_key": "50620032600206270652001000010100000000011XXXXXXXX",
            "voucher_type": "01",
            "voucher_type_label": "Factura Electrónica",
            "consecutive_number": "00100001010000000001",
            "issued_at": "2026-03-20T10:30:00-06:00",
            "situation": "1",
            "sale_condition": "01",
            "sale_condition_label": "Contado",
            "receiver": {
                "id_type": "02",
                "id_number": "3102345678",
                "name": "Empresa S.A."
            },
            "currency_code": "CRC",
            "total_comprobante": "56500.00000",
            "status": "accepted",
            "hacienda": {
                "status": "aceptado",
                "sent_at": "2026-03-20T10:31:00-06:00",
                "processed_at": "2026-03-20T10:32:00-06:00"
            },
            "environment": "sandbox",
            "is_xml_available": true,
            "line_items_count": 3,
            "created_at": "2026-03-20T10:30:00-06:00",
            "updated_at": "2026-03-20T10:32:00-06:00"
        }
    ],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 72,
        "from": 1,
        "to": 15
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"voucher_type\": \"01\",
    \"situation\": \"1\",
    \"issued_at\": \"2026-04-20T10:30:00-06:00\",
    \"issuer_activity_code\": \"6201.0\",
    \"receiver_activity_code\": \"4711.0\",
    \"sale_condition\": \"01\",
    \"sale_condition_other\": \"Acuerdo especial de intercambio\",
    \"credit_term\": \"30\",
    \"currency_code\": \"CRC\",
    \"exchange_rate\": \"1.00000\",
    \"client_id\": \"019d1234-0000-0000-0000-000000000001\",
    \"managed_contributor_id\": \"019d867d-0241-7288-8ece-fd64da75616d\",
    \"receiver\": {
        \"name\": \"Empresa Ejemplo S.A.\",
        \"id_type\": \"02\",
        \"id_number\": \"3101000001\",
        \"commercial_name\": \"b\",
        \"emails\": [
            \"architecto\"
        ],
        \"province\": 2,
        \"canton\": \"56\",
        \"district\": \"56\",
        \"address\": \"i\",
        \"phone_country_code\": 8,
        \"phone\": \"564255931\"
    },
    \"line_items\": [
        {
            \"item_id\": \"019d1234-0000-0000-0000-000000000002\",
            \"line_number\": 1,
            \"cabys_code\": \"5311100000000\",
            \"arancelary_partition\": \"564255931423\",
            \"quantity\": \"1.000\",
            \"unit_of_measure\": \"Unid\",
            \"detail\": \"Servicio de consultoría\",
            \"unit_price\": \"10000.00000\",
            \"total_amount\": \"10000.00000\",
            \"sub_total\": \"10000.00000\",
            \"base_imponible\": \"10000.00000\",
            \"discounts\": [
                {
                    \"monto\": 39,
                    \"codigo\": 6
                }
            ],
            \"taxes\": [
                {
                    \"codigo\": \"01\",
                    \"codigoTarifa\": \"08\",
                    \"tarifa\": \"13.00\",
                    \"monto\": \"1300.00000\",
                    \"monto_exportacion\": 50,
                    \"exoneracion\": {
                        \"tipoDocumento\": \"kc\",
                        \"numeroDocumento\": \"m\",
                        \"nombreInstitucion\": \"y\",
                        \"fechaEmision\": \"2026-04-29T10:12:07\",
                        \"tarifaExonerada\": 72,
                        \"montoExoneracion\": 61
                    }
                }
            ],
            \"impuesto_neto\": \"1300.00000\",
            \"total_line_amount\": \"11300.00000\",
            \"medicine_registration\": \"p\",
            \"pharma_form_code\": \"564\",
            \"commercial_codes\": [
                {
                    \"tipo\": 2,
                    \"codigo\": \"yvdljnikhwaykcmy\"
                }
            ],
            \"vin_numbers\": [
                \"u\"
            ]
        }
    ],
    \"references\": [
        {
            \"doc_type\": \"01\",
            \"number\": \"50613032600206270652001000010100000000001XXXXXXXX\",
            \"issued_at\": \"2026-03-01T10:00:00-06:00\",
            \"code\": \"01\",
            \"reason\": \"Anulación por error en monto\"
        }
    ],
    \"payment_methods\": [
        {
            \"tipo\": \"01\"
        }
    ],
    \"other_charges\": [
        {
            \"tipo\": \"06\",
            \"description\": \"Quidem nostrum qui commodi incidunt iure odit.\",
            \"percentage\": 10,
            \"amount\": 5000
        }
    ]
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "voucher_type": "01",
    "situation": "1",
    "issued_at": "2026-04-20T10:30:00-06:00",
    "issuer_activity_code": "6201.0",
    "receiver_activity_code": "4711.0",
    "sale_condition": "01",
    "sale_condition_other": "Acuerdo especial de intercambio",
    "credit_term": "30",
    "currency_code": "CRC",
    "exchange_rate": "1.00000",
    "client_id": "019d1234-0000-0000-0000-000000000001",
    "managed_contributor_id": "019d867d-0241-7288-8ece-fd64da75616d",
    "receiver": {
        "name": "Empresa Ejemplo S.A.",
        "id_type": "02",
        "id_number": "3101000001",
        "commercial_name": "b",
        "emails": [
            "architecto"
        ],
        "province": 2,
        "canton": "56",
        "district": "56",
        "address": "i",
        "phone_country_code": 8,
        "phone": "564255931"
    },
    "line_items": [
        {
            "item_id": "019d1234-0000-0000-0000-000000000002",
            "line_number": 1,
            "cabys_code": "5311100000000",
            "arancelary_partition": "564255931423",
            "quantity": "1.000",
            "unit_of_measure": "Unid",
            "detail": "Servicio de consultoría",
            "unit_price": "10000.00000",
            "total_amount": "10000.00000",
            "sub_total": "10000.00000",
            "base_imponible": "10000.00000",
            "discounts": [
                {
                    "monto": 39,
                    "codigo": 6
                }
            ],
            "taxes": [
                {
                    "codigo": "01",
                    "codigoTarifa": "08",
                    "tarifa": "13.00",
                    "monto": "1300.00000",
                    "monto_exportacion": 50,
                    "exoneracion": {
                        "tipoDocumento": "kc",
                        "numeroDocumento": "m",
                        "nombreInstitucion": "y",
                        "fechaEmision": "2026-04-29T10:12:07",
                        "tarifaExonerada": 72,
                        "montoExoneracion": 61
                    }
                }
            ],
            "impuesto_neto": "1300.00000",
            "total_line_amount": "11300.00000",
            "medicine_registration": "p",
            "pharma_form_code": "564",
            "commercial_codes": [
                {
                    "tipo": 2,
                    "codigo": "yvdljnikhwaykcmy"
                }
            ],
            "vin_numbers": [
                "u"
            ]
        }
    ],
    "references": [
        {
            "doc_type": "01",
            "number": "50613032600206270652001000010100000000001XXXXXXXX",
            "issued_at": "2026-03-01T10:00:00-06:00",
            "code": "01",
            "reason": "Anulación por error en monto"
        }
    ],
    "payment_methods": [
        {
            "tipo": "01"
        }
    ],
    "other_charges": [
        {
            "tipo": "06",
            "description": "Quidem nostrum qui commodi incidunt iure odit.",
            "percentage": 10,
            "amount": 5000
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'voucher_type' => '01',
            'situation' => '1',
            'issued_at' => '2026-04-20T10:30:00-06:00',
            'issuer_activity_code' => '6201.0',
            'receiver_activity_code' => '4711.0',
            'sale_condition' => '01',
            'sale_condition_other' => 'Acuerdo especial de intercambio',
            'credit_term' => '30',
            'currency_code' => 'CRC',
            'exchange_rate' => '1.00000',
            'client_id' => '019d1234-0000-0000-0000-000000000001',
            'managed_contributor_id' => '019d867d-0241-7288-8ece-fd64da75616d',
            'receiver' => [
                'name' => 'Empresa Ejemplo S.A.',
                'id_type' => '02',
                'id_number' => '3101000001',
                'commercial_name' => 'b',
                'emails' => [
                    'architecto',
                ],
                'province' => 2,
                'canton' => '56',
                'district' => '56',
                'address' => 'i',
                'phone_country_code' => 8,
                'phone' => '564255931',
            ],
            'line_items' => [
                [
                    'item_id' => '019d1234-0000-0000-0000-000000000002',
                    'line_number' => 1,
                    'cabys_code' => '5311100000000',
                    'arancelary_partition' => '564255931423',
                    'quantity' => '1.000',
                    'unit_of_measure' => 'Unid',
                    'detail' => 'Servicio de consultoría',
                    'unit_price' => '10000.00000',
                    'total_amount' => '10000.00000',
                    'sub_total' => '10000.00000',
                    'base_imponible' => '10000.00000',
                    'discounts' => [
                        [
                            'monto' => 39,
                            'codigo' => 6,
                        ],
                    ],
                    'taxes' => [
                        [
                            'codigo' => '01',
                            'codigoTarifa' => '08',
                            'tarifa' => '13.00',
                            'monto' => '1300.00000',
                            'monto_exportacion' => 50,
                            'exoneracion' => [
                                'tipoDocumento' => 'kc',
                                'numeroDocumento' => 'm',
                                'nombreInstitucion' => 'y',
                                'fechaEmision' => '2026-04-29T10:12:07',
                                'tarifaExonerada' => 72,
                                'montoExoneracion' => 61,
                            ],
                        ],
                    ],
                    'impuesto_neto' => '1300.00000',
                    'total_line_amount' => '11300.00000',
                    'medicine_registration' => 'p',
                    'pharma_form_code' => '564',
                    'commercial_codes' => [
                        [
                            'tipo' => 2,
                            'codigo' => 'yvdljnikhwaykcmy',
                        ],
                    ],
                    'vin_numbers' => [
                        'u',
                    ],
                ],
            ],
            'references' => [
                [
                    'doc_type' => '01',
                    'number' => '50613032600206270652001000010100000000001XXXXXXXX',
                    'issued_at' => '2026-03-01T10:00:00-06:00',
                    'code' => '01',
                    'reason' => 'Anulación por error en monto',
                ],
            ],
            'payment_methods' => [
                [
                    'tipo' => '01',
                ],
            ],
            'other_charges' => [
                [
                    'tipo' => '06',
                    'description' => 'Quidem nostrum qui commodi incidunt iure odit.',
                    'percentage' => 10,
                    'amount' => 5000.0,
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (202, Comprobante emitido correctamente):

{
    "success": true,
    "data": {
        "voucher_key": "50620042600206270652001000010100000000011XXXXXXXX",
        "voucher_type": "01",
        "voucher_type_label": "Factura Electrónica",
        "consecutive_number": "00100001010000000001",
        "issued_at": "2026-04-20T10:30:00-06:00",
        "situation": "1",
        "situation_label": "Normal",
        "sale_condition": "01",
        "sale_condition_label": "Contado",
        "sale_condition_other": null,
        "credit_term": null,
        "receiver": {
            "id_type": "02",
            "id_number": "3101000001",
            "name": "EMPRESA EJEMPLO S.A.",
            "commercial_name": null,
            "emails": [
                "facturacion@ejemplo.cr"
            ]
        },
        "currency_code": "CRC",
        "exchange_rate": "1.00000",
        "totals": {
            "serv_gravados": "10000.00000",
            "serv_exentos": "0.00000",
            "serv_exonerado": "0.00000",
            "serv_no_sujeto": "0.00000",
            "merc_gravadas": "0.00000",
            "merc_exentas": "0.00000",
            "merc_exonerada": "0.00000",
            "merc_no_sujeta": "0.00000",
            "total_gravado": "10000.00000",
            "total_exento": "0.00000",
            "total_exonerado": "0.00000",
            "total_no_sujeto": "0.00000",
            "total_venta": "10000.00000",
            "total_descuentos": "0.00000",
            "total_venta_neta": "10000.00000",
            "total_impuesto": "1300.00000",
            "total_imp_asum_emisor_fab": "0.00000",
            "total_iva_devuelto": "0.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "11300.00000"
        },
        "payment_methods": [
            {
                "tipo": "01"
            }
        ],
        "status": "pending",
        "hacienda": {
            "status": null,
            "message": null,
            "sent_at": null,
            "processed_at": null
        },
        "environment": "production",
        "is_xml_available": true,
        "line_items_count": 1,
        "references_count": 0,
        "created_at": "2026-04-20T10:30:00-06:00",
        "updated_at": "2026-04-20T10:30:00-06:00"
    },
    "message": "Comprobante [50620042600206270652001000010100000000011XXXXXXXX] generado y encolado para envío a Hacienda.",
    "errors": null
}
 

Example response (422, Error de validación del payload):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "voucher_type": [
            "El campo voucher_type es obligatorio."
        ]
    }
}
 

Example response (422, Error de validación XSD (no consume consecutivo)):

{
    "success": false,
    "data": null,
    "message": "Validación XSD fallida para Factura Electrónica (01) — 1 error. Primer error: [45:12] Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'.",
    "errors": {
        "voucher_type": [
            "01"
        ],
        "xsd": [
            {
                "nivel": "error",
                "codigo": 1824,
                "linea": 45,
                "columna": 12,
                "mensaje": "Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'."
            }
        ]
    }
}
 

Example response (422, Error de firma digital (consume consecutivo)):

{
    "success": false,
    "data": null,
    "message": "No se pudo firmar el comprobante. El certificado digital está vencido. Renueve su certificado con el BCCR y vuelva a subirlo.",
    "errors": {
        "signature": [
            "..."
        ],
        "code": [
            "2002"
        ]
    }
}
 

Example response (422, Cupo mensual agotado):

{
    "success": false,
    "data": null,
    "message": "Ha alcanzado el límite mensual de comprobantes de su plan.",
    "errors": {
        "plan": [
            "Actualice a un plan superior o active overage para continuar emitiendo."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency?situation=3&expired_only=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency"
);

const params = {
    "situation": "3",
    "expired_only": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'situation' => '3',
            'expired_only' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Con comprobantes pendientes):

{
    "success": true,
    "data": {
        "items": [
            {
                "voucher_key": "50617042026...",
                "voucher_type": "01",
                "voucher_type_label": "Factura Electrónica",
                "consecutive_number": "00100001010000000001",
                "status": "error",
                "situation": "3",
                "situation_label": "Sin Internet",
                "issued_at": "2026-04-10T14:30:00-06:00",
                "deadline": "2026-04-14",
                "elapsed_business_days": 3,
                "is_expired": true,
                "receiver": {
                    "id_type": "02",
                    "id_number": "3101000001",
                    "name": "Empresa S.A."
                },
                "currency_code": "CRC",
                "total_comprobante": "56500.00000"
            }
        ],
        "total": 5,
        "expired_count": 2
    },
    "message": "5 comprobante(s) de contingencia sin resolver. 2 superan el plazo de 2 días hábiles.",
    "errors": null
}
 

Example response (200, Sin pendientes):

{
    "success": true,
    "data": {
        "items": [],
        "total": 0,
        "expired_count": 0
    },
    "message": "Sin comprobantes de contingencia pendientes.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Comprobante encontrado):

{
    "success": true,
    "data": {
        "voucher_key": "50619032600310199999900100001010000000001112345678",
        "voucher_type": "01",
        "voucher_type_label": "Factura Electrónica",
        "consecutive_number": "00100001010000000001",
        "issued_at": "2026-04-13T10:00:00-06:00",
        "situation": "1",
        "situation_label": "Normal",
        "sale_condition": "01",
        "sale_condition_label": "Contado",
        "sale_condition_other": null,
        "credit_term": null,
        "receiver": {
            "id_type": "02",
            "id_number": "3101000001",
            "name": "EMPRESA EJEMPLO S.A.",
            "commercial_name": "Ejemplo Comercial",
            "emails": [
                "facturacion@ejemplo.cr"
            ]
        },
        "currency_code": "CRC",
        "exchange_rate": "1.00000",
        "totals": {
            "serv_gravados": "10000.00000",
            "serv_exentos": "0.00000",
            "serv_exonerado": "0.00000",
            "serv_no_sujeto": "0.00000",
            "merc_gravadas": "0.00000",
            "merc_exentas": "0.00000",
            "merc_exonerada": "0.00000",
            "merc_no_sujeta": "0.00000",
            "total_gravado": "10000.00000",
            "total_exento": "0.00000",
            "total_exonerado": "0.00000",
            "total_no_sujeto": "0.00000",
            "total_venta": "10000.00000",
            "total_descuentos": "0.00000",
            "total_venta_neta": "10000.00000",
            "total_impuesto": "1300.00000",
            "total_imp_asum_emisor_fab": "0.00000",
            "total_iva_devuelto": "0.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "11300.00000"
        },
        "payment_methods": [
            {
                "tipo": "01"
            }
        ],
        "status": "accepted",
        "hacienda": {
            "status": "aceptado",
            "message": null,
            "sent_at": "2026-04-13T10:01:00-06:00",
            "processed_at": "2026-04-13T10:02:00-06:00"
        },
        "environment": "production",
        "is_xml_available": true,
        "line_items_count": 1,
        "references_count": 0,
        "created_at": "2026-04-13T10:00:00-06:00",
        "updated_at": "2026-04-13T10:02:00-06:00"
    },
    "message": "Comprobante obtenido correctamente.",
    "errors": null
}
 

Example response (404, Comprobante no encontrado):

{
    "success": false,
    "data": null,
    "message": "El recurso solicitado no existe.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (202, NC de anulación generada):

{
    "success": true,
    "data": {
        "voucher_key": "50621042600310199999900100001010000000002212345679",
        "voucher_type": "03",
        "voucher_type_label": "Nota de Crédito",
        "consecutive_number": "00100001030000000001",
        "status": "pending",
        "environment": "production",
        "created_at": "2026-04-21T11:00:00-06:00"
    },
    "message": "NC de anulación generada. Encolada para envío a Hacienda.",
    "errors": null
}
 

Example response (409, El estado no permite anulación):

{
    "success": false,
    "data": null,
    "message": "Solo comprobantes aceptados por Hacienda pueden anularse.",
    "errors": null
}
 

Example response (422, Error de validación XSD de la NC):

{
    "success": false,
    "data": null,
    "message": "Validación XSD fallida para Nota de Crédito (03) — ...",
    "errors": {
        "voucher_type": [
            "03"
        ],
        "xsd": [
            {
                "linea": 45,
                "columna": 12,
                "mensaje": "..."
            }
        ]
    }
}
 

Example response (422, Error de firma de la NC):

{
    "success": false,
    "data": null,
    "message": "No se pudo firmar el comprobante. El certificado digital está vencido.",
    "errors": {
        "signature": [
            "..."
        ],
        "code": [
            "2002"
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, XML disponible):

[archivo binario application/xml]
 

Example response (404, XML aún no generado):

{
    "success": false,
    "data": null,
    "message": "El XML firmado aún no está disponible. El comprobante está en estado 'draft'.",
    "errors": null
}
 

Example response (410, XML purgado — retención expirada):

{
    "success": false,
    "data": null,
    "message": "XML purgado. Retención expirada el 2026-06-15.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, XML respuesta disponible):

[archivo binario application/xml]
 

Example response (404, Respuesta aún no disponible):

{
    "success": false,
    "data": null,
    "message": "La respuesta de Hacienda aún no está disponible. El comprobante está en estado 'sent'.",
    "errors": null
}
 

Example response (410, XML purgado — retención expirada):

{
    "success": false,
    "data": null,
    "message": "XML purgado. Retención expirada el 2026-06-15.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf?template_id=16" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf"
);

const params = {
    "template_id": "16",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'template_id' => '16',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, PDF generado):

[archivo binario application/pdf]
 

Example response (404, Comprobante en draft):

{
    "success": false,
    "data": null,
    "message": "El PDF no está disponible. El comprobante está en estado 'draft'.",
    "errors": null
}
 

Example response (404, Sin plantilla PDF default activa):

{
    "success": false,
    "data": null,
    "message": "El contribuyente no tiene plantilla PDF default activa.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/profile/usage" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile/usage"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile/usage';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Contribuyente normal):

{
    "success": true,
    "data": {
        "vouchers_this_month": 87,
        "vouchers_limit": 500,
        "vouchers_remaining": 413,
        "vouchers_percentage": 17.4,
        "emails_today": 12,
        "emails_limit": 75,
        "period_start": "2026-04-01",
        "period_end": "2026-04-30"
    },
    "message": "Estadísticas de uso mensual.",
    "errors": null
}
 

Example response (200, Integrador (consumo agregado con todos sus clientes)):

{
    "success": true,
    "data": {
        "vouchers_this_month": 12450,
        "vouchers_limit": 50000,
        "vouchers_remaining": 37550,
        "vouchers_percentage": 24.9,
        "emails_today": 0,
        "emails_limit": 5000,
        "period_start": "2026-04-01",
        "period_end": "2026-04-30"
    },
    "message": "Estadísticas de uso mensual.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/profile" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Perfil completo):

{
    "success": true,
    "data": {
        "id": "019d867d-0241-7288-8ece-fd64da75616d",
        "legal_name": "Empresa Ejemplo S.A.",
        "trade_name": "Ejemplo Shop",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101000000",
        "emails": [
            "facturacion@empresa.cr"
        ],
        "economic_activities": [
            "6201.0"
        ],
        "location": {
            "province": 1,
            "canton": 1,
            "district": 1
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "is_active": true,
        "production_enabled": false,
        "hacienda_environment": "sandbox",
        "plan_id": "019d0001-0000-0000-0000-000000000001",
        "is_managed": false,
        "is_integrator": false,
        "plan": {
            "id": "019d0001-0000-0000-0000-000000000001",
            "code": "pyme",
            "name": "Pyme",
            "description": "Automatice su facturación con hasta 500 comprobantes/mes.",
            "monthly_price_usd": null,
            "annual_price_usd": 96,
            "billing_mode": "annual_only",
            "annual_discount_percent": 0,
            "vouchers_per_month": 500,
            "overage_price_per_voucher": 0.03,
            "max_users": 3,
            "max_api_tokens": 2,
            "max_clients": 300,
            "max_items": 750,
            "max_pdf_templates": 1,
            "max_daily_emails": 75,
            "max_webhook_endpoints": 1,
            "max_branch_terminals": 2,
            "max_managed_contributors": 1,
            "api_rate_limit_per_minute": 20,
            "retention_months": 3,
            "extended_retention_eligible": true,
            "pdf_branding": "platform",
            "api_write_enabled": true,
            "api_readonly_enabled": false,
            "sandbox_access": true,
            "webhooks_enabled": false,
            "multi_contributor": false,
            "receiver_module": true,
            "bulk_emission": false,
            "sla_support": false
        },
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-13T14:30:00-06:00"
    },
    "message": "Perfil del contribuyente.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/profile" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"id_number\": \"3101000000\",
    \"legal_name\": \"Empresa Ejemplo S.A.\",
    \"trade_name\": \"Ejemplo Tienda\",
    \"emails\": [
        \"facturacion@empresa.cr\"
    ],
    \"economic_activities\": [
        \"6201.0\"
    ],
    \"phone\": \"22001234\",
    \"phone_country_code\": 506,
    \"province\": 1,
    \"canton\": 1,
    \"district\": 1,
    \"neighborhood\": \"San Pedro\",
    \"address\": \"200 metros norte del parque central\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "id_number": "3101000000",
    "legal_name": "Empresa Ejemplo S.A.",
    "trade_name": "Ejemplo Tienda",
    "emails": [
        "facturacion@empresa.cr"
    ],
    "economic_activities": [
        "6201.0"
    ],
    "phone": "22001234",
    "phone_country_code": 506,
    "province": 1,
    "canton": 1,
    "district": 1,
    "neighborhood": "San Pedro",
    "address": "200 metros norte del parque central"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'id_number' => '3101000000',
            'legal_name' => 'Empresa Ejemplo S.A.',
            'trade_name' => 'Ejemplo Tienda',
            'emails' => [
                'facturacion@empresa.cr',
            ],
            'economic_activities' => [
                '6201.0',
            ],
            'phone' => '22001234',
            'phone_country_code' => 506,
            'province' => 1,
            'canton' => 1,
            'district' => 1,
            'neighborhood' => 'San Pedro',
            'address' => '200 metros norte del parque central',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Perfil actualizado):

{
    "success": true,
    "data": {
        "id": "019d867d-0241-7288-8ece-fd64da75616d",
        "legal_name": "Empresa Ejemplo S.A. Actualizada",
        "trade_name": "Ejemplo Shop Nuevo",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101000000",
        "emails": [
            "facturacion@empresa.cr",
            "contabilidad@empresa.cr"
        ],
        "economic_activities": [
            "6201.0",
            "4711.0"
        ],
        "location": {
            "province": 1,
            "canton": 1,
            "district": 1
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "is_active": true,
        "production_enabled": false,
        "hacienda_environment": "sandbox",
        "plan_id": "019d0001-0000-0000-0000-000000000001",
        "is_managed": false,
        "is_integrator": false,
        "plan": {
            "id": "019d0001-0000-0000-0000-000000000001",
            "code": "pyme",
            "name": "Pyme",
            "vouchers_per_month": 500,
            "max_clients": 300,
            "sandbox_access": true
        },
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T09:15:00-06:00"
    },
    "message": "Perfil actualizado correctamente.",
    "errors": null
}
 

Example response (422, Error de validación):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "emails.0": [
            "El campo emails.0 debe ser un correo electrónico válido."
        ],
        "economic_activities.0": [
            "El formato del código de actividad económica debe ser XXXX.X (ejemplo: 6201.0)."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/certificates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listado con activo e histórico):

{
    "success": true,
    "data": [
        {
            "id": "019d867d-1111-7288-8ece-fd64da756001",
            "environment": "sandbox",
            "is_active": true,
            "is_expired": false,
            "days_remaining": 120,
            "valid_from": "2024-01-01T00:00:00-06:00",
            "valid_until": "2026-08-15T23:59:59-06:00",
            "certificate_subject": "CN=EMPRESA EJEMPLO S.A., serialNumber=3101000001",
            "certificate_serial": "0A1B2C3D4E5F",
            "created_at": "2026-04-09T10:00:00-06:00"
        },
        {
            "id": "019d867d-2222-7288-8ece-fd64da756002",
            "environment": "sandbox",
            "is_active": false,
            "is_expired": true,
            "days_remaining": 0,
            "valid_from": "2022-01-01T00:00:00-06:00",
            "valid_until": "2024-01-01T00:00:00-06:00",
            "certificate_subject": "CN=EMPRESA EJEMPLO S.A., serialNumber=3101000001",
            "certificate_serial": "AA11BB22CC33",
            "created_at": "2024-01-10T08:00:00-06:00"
        }
    ],
    "message": "",
    "errors": null
}
 

Example response (200, Sin certificados cargados):

{
    "success": true,
    "data": [],
    "message": "",
    "errors": null
}
 

Example response (401, No autenticado):

{
    "success": false,
    "data": null,
    "message": "Unauthenticated.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/certificates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "p12_password=MiContrasenaDelP12"\
    --form "hacienda_pin=1234"\
    --form "environment=sandbox"\
    --form "p12_file=@/tmp/phpgrm2i4vq3o9baKpptFj" 

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('p12_password', 'MiContrasenaDelP12');
body.append('hacienda_pin', '1234');
body.append('environment', 'sandbox');
body.append('p12_file', document.querySelector('input[name="p12_file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'p12_password',
                'contents' => 'MiContrasenaDelP12'
            ],
            [
                'name' => 'hacienda_pin',
                'contents' => '1234'
            ],
            [
                'name' => 'environment',
                'contents' => 'sandbox'
            ],
            [
                'name' => 'p12_file',
                'contents' => fopen('/tmp/phpgrm2i4vq3o9baKpptFj', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Certificado registrado y activado):

{
    "success": true,
    "data": {
        "id": "019d867d-3333-7288-8ece-fd64da756003",
        "environment": "sandbox",
        "is_active": true,
        "is_expired": false,
        "days_remaining": 730,
        "valid_from": "2026-01-01T00:00:00-06:00",
        "valid_until": "2028-01-01T00:00:00-06:00",
        "certificate_subject": "CN=EMPRESA EJEMPLO S.A., serialNumber=3101000001",
        "certificate_serial": "0A1B2C3D4E5F",
        "created_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Certificado registrado y activado correctamente.",
    "errors": null
}
 

Example response (422, Contraseña incorrecta del .p12):

{
    "success": false,
    "data": null,
    "message": "No se pudo leer el certificado .p12. Verifique que la contraseña sea correcta y que el archivo sea un certificado digital válido.",
    "errors": {
        "p12_file": [
            "No se pudo leer el certificado .p12. Verifique que la contraseña sea correcta y que el archivo sea un certificado digital válido."
        ]
    }
}
 

Example response (422, Archivo no es un .p12 válido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "p12_file": [
            "El archivo debe tener extensión .p12 o .pfx."
        ]
    }
}
 

Example response (422, Ambiente inválido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "environment": [
            "El ambiente seleccionado no es válido. Use sandbox o production."
        ]
    }
}
 

Example response (422, Falta el PIN de Hacienda):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "hacienda_pin": [
            "El PIN de Hacienda es obligatorio."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Certificado desactivado (sin accesos asociados)):

{
    "success": true,
    "data": null,
    "message": "Certificado desactivado correctamente.",
    "errors": null
}
 

Example response (200, Certificado desactivado con auto-revocación de accesos):

{
    "success": true,
    "data": null,
    "message": "Certificado desactivado correctamente. Se revocaron 2 accesos de integradores asociados.",
    "errors": null
}
 

Example response (404, Certificado no encontrado o no pertenece al contribuyente):

{
    "success": false,
    "data": null,
    "message": "Certificado no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/pdf-templates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listado de plantillas (default primero)):

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Classic",
            "is_default": true,
            "paper_size": "letter",
            "config_json": {
                "colors": {
                    "primary": "#2d3748",
                    "secondary": "#4a5568",
                    "accent": "#3182ce"
                },
                "fonts": {
                    "family": "Helvetica",
                    "size_title": 14,
                    "size_body": 9
                },
                "layout": {
                    "show_logo": true,
                    "logo_position": "left",
                    "logo_max_height": 60
                },
                "qr": {
                    "enabled": true,
                    "size": 100,
                    "position": "bottom-right"
                }
            },
            "has_logo": true,
            "is_active": true,
            "created_at": "2026-04-01T10:00:00-06:00",
            "updated_at": "2026-04-10T14:30:00-06:00"
        },
        {
            "id": 2,
            "name": "Minimal",
            "is_default": false,
            "paper_size": "A4",
            "config_json": {
                "colors": {
                    "primary": "#000000",
                    "secondary": "#666666",
                    "accent": "#000000"
                },
                "fonts": {
                    "family": "Helvetica",
                    "size_title": 12,
                    "size_body": 8
                },
                "layout": {
                    "show_logo": false,
                    "logo_position": "left",
                    "logo_max_height": 60
                },
                "qr": {
                    "enabled": true,
                    "size": 80,
                    "position": "bottom-right"
                }
            },
            "has_logo": false,
            "is_active": true,
            "created_at": "2026-04-05T08:00:00-06:00",
            "updated_at": "2026-04-05T08:00:00-06:00"
        }
    ],
    "message": "",
    "errors": null
}
 

Example response (401, No autenticado):

{
    "success": false,
    "data": null,
    "message": "Unauthenticated.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Mi Plantilla Corporativa\",
    \"is_default\": false,
    \"paper_size\": \"letter\",
    \"config_json\": {
        \"colors\": {
            \"primary\": \"#0a66c2\",
            \"secondary\": \"#333333\",
            \"accent\": \"#0a66c2\"
        },
        \"fonts\": {
            \"family\": \"Helvetica\",
            \"size_title\": 14,
            \"size_body\": 9
        },
        \"layout\": {
            \"show_logo\": true,
            \"logo_position\": \"left\",
            \"logo_max_height\": 60
        },
        \"qr\": {
            \"enabled\": true,
            \"size\": 100,
            \"position\": \"bottom-right\"
        },
        \"margins\": {
            \"top\": 15,
            \"right\": 15,
            \"bottom\": 15,
            \"left\": 15
        },
        \"style\": \"classic\",
        \"footer_text\": \"Documento generado electrónicamente | Almendro Factura Electrónica\"
    }
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Mi Plantilla Corporativa",
    "is_default": false,
    "paper_size": "letter",
    "config_json": {
        "colors": {
            "primary": "#0a66c2",
            "secondary": "#333333",
            "accent": "#0a66c2"
        },
        "fonts": {
            "family": "Helvetica",
            "size_title": 14,
            "size_body": 9
        },
        "layout": {
            "show_logo": true,
            "logo_position": "left",
            "logo_max_height": 60
        },
        "qr": {
            "enabled": true,
            "size": 100,
            "position": "bottom-right"
        },
        "margins": {
            "top": 15,
            "right": 15,
            "bottom": 15,
            "left": 15
        },
        "style": "classic",
        "footer_text": "Documento generado electrónicamente | Almendro Factura Electrónica"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Mi Plantilla Corporativa',
            'is_default' => false,
            'paper_size' => 'letter',
            'config_json' => [
                'colors' => [
                    'primary' => '#0a66c2',
                    'secondary' => '#333333',
                    'accent' => '#0a66c2',
                ],
                'fonts' => [
                    'family' => 'Helvetica',
                    'size_title' => 14,
                    'size_body' => 9,
                ],
                'layout' => [
                    'show_logo' => true,
                    'logo_position' => 'left',
                    'logo_max_height' => 60,
                ],
                'qr' => [
                    'enabled' => true,
                    'size' => 100,
                    'position' => 'bottom-right',
                ],
                'margins' => [
                    'top' => 15,
                    'right' => 15,
                    'bottom' => 15,
                    'left' => 15,
                ],
                'style' => 'classic',
                'footer_text' => 'Documento generado electrónicamente | Almendro Factura Electrónica',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Plantilla creada):

{
    "success": true,
    "data": {
        "id": 3,
        "name": "Mi Plantilla Corporativa",
        "is_default": false,
        "paper_size": "letter",
        "config_json": {
            "colors": {
                "primary": "#0a66c2",
                "secondary": "#333333",
                "accent": "#0a66c2"
            },
            "fonts": {
                "family": "Helvetica",
                "size_title": 14,
                "size_body": 9
            },
            "layout": {
                "show_logo": true,
                "logo_position": "left",
                "logo_max_height": 60
            },
            "qr": {
                "enabled": true,
                "size": 100,
                "position": "bottom-right"
            }
        },
        "has_logo": false,
        "is_active": true,
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Plantilla creada correctamente.",
    "errors": null
}
 

Example response (422, Nombre duplicado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "name": [
            "Ya existe una plantilla con este nombre para el contribuyente."
        ]
    }
}
 

Example response (422, Color hexadecimal inválido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "config_json.colors.primary": [
            "El color debe ser un hexadecimal válido (ej. #1a365d)."
        ]
    }
}
 

Example response (422, Tamaño del QR por debajo del mínimo normativo):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "config_json.qr.size": [
            "El tamaño mínimo del QR es 70 pt (≈ 2.5 cm) por normativa."
        ]
    }
}
 

Example response (422, Límite del plan alcanzado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "plan": [
            "Ha alcanzado el límite de plantillas PDF de su plan. Actualice a un plan superior."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Profesional Actualizada\",
    \"is_default\": true,
    \"is_active\": true,
    \"paper_size\": \"letter\",
    \"config_json\": {
        \"colors\": {
            \"primary\": \"#1a365d\",
            \"secondary\": \"#4a5568\",
            \"text\": \"#2815Df\",
            \"accent\": \"#3182ce\"
        },
        \"fonts\": {
            \"family\": \"Helvetica\",
            \"size_header\": 2,
            \"size_body\": 9,
            \"size_footer\": 3,
            \"size_title\": 14
        },
        \"layout\": {
            \"show_logo\": true,
            \"logo_position\": \"left\",
            \"logo_max_height\": 60,
            \"show_commercial_name\": true,
            \"show_address\": true,
            \"show_phone\": true,
            \"show_email\": false,
            \"show_observations\": false,
            \"show_payment_methods\": true,
            \"show_references\": false,
            \"show_other_charges\": false
        },
        \"qr\": {
            \"size\": 100,
            \"position\": \"bottom-right\"
        },
        \"margins\": {
            \"top\": 22,
            \"right\": 24,
            \"bottom\": 18,
            \"left\": 8
        },
        \"style\": \"modern\",
        \"footer_text\": \"m\"
    }
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Profesional Actualizada",
    "is_default": true,
    "is_active": true,
    "paper_size": "letter",
    "config_json": {
        "colors": {
            "primary": "#1a365d",
            "secondary": "#4a5568",
            "text": "#2815Df",
            "accent": "#3182ce"
        },
        "fonts": {
            "family": "Helvetica",
            "size_header": 2,
            "size_body": 9,
            "size_footer": 3,
            "size_title": 14
        },
        "layout": {
            "show_logo": true,
            "logo_position": "left",
            "logo_max_height": 60,
            "show_commercial_name": true,
            "show_address": true,
            "show_phone": true,
            "show_email": false,
            "show_observations": false,
            "show_payment_methods": true,
            "show_references": false,
            "show_other_charges": false
        },
        "qr": {
            "size": 100,
            "position": "bottom-right"
        },
        "margins": {
            "top": 22,
            "right": 24,
            "bottom": 18,
            "left": 8
        },
        "style": "modern",
        "footer_text": "m"
    }
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Profesional Actualizada',
            'is_default' => true,
            'is_active' => true,
            'paper_size' => 'letter',
            'config_json' => [
                'colors' => [
                    'primary' => '#1a365d',
                    'secondary' => '#4a5568',
                    'text' => '#2815Df',
                    'accent' => '#3182ce',
                ],
                'fonts' => [
                    'family' => 'Helvetica',
                    'size_header' => 2,
                    'size_body' => 9,
                    'size_footer' => 3,
                    'size_title' => 14,
                ],
                'layout' => [
                    'show_logo' => true,
                    'logo_position' => 'left',
                    'logo_max_height' => 60,
                    'show_commercial_name' => true,
                    'show_address' => true,
                    'show_phone' => true,
                    'show_email' => false,
                    'show_observations' => false,
                    'show_payment_methods' => true,
                    'show_references' => false,
                    'show_other_charges' => false,
                ],
                'qr' => [
                    'size' => 100,
                    'position' => 'bottom-right',
                ],
                'margins' => [
                    'top' => 22,
                    'right' => 24,
                    'bottom' => 18,
                    'left' => 8,
                ],
                'style' => 'modern',
                'footer_text' => 'm',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Plantilla actualizada):

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Profesional Actualizada",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {
                "primary": "#1a365d",
                "secondary": "#4a5568",
                "accent": "#3182ce"
            },
            "fonts": {
                "family": "Helvetica",
                "size_title": 14,
                "size_body": 9
            },
            "layout": {
                "show_logo": true,
                "logo_position": "left",
                "logo_max_height": 60
            },
            "qr": {
                "enabled": true,
                "size": 100,
                "position": "bottom-right"
            }
        },
        "has_logo": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T11:00:00-06:00"
    },
    "message": "Plantilla actualizada correctamente.",
    "errors": null
}
 

Example response (404, Plantilla no encontrada):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Example response (422, Nombre duplicado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "name": [
            "Ya existe una plantilla con este nombre para el contribuyente."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/2" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/2"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/2';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Plantilla eliminada):

{
    "success": true,
    "data": null,
    "message": "Plantilla eliminada correctamente.",
    "errors": null
}
 

Example response (404, Plantilla no encontrada):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Example response (409, No se puede eliminar la única plantilla activa):

{
    "success": false,
    "data": null,
    "message": "No se puede eliminar la única plantilla activa del contribuyente. Cree otra plantilla o marque otra como default antes de eliminar.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, PDF generado exitosamente):

{
    "Content-Type": "application/pdf",
    "Content-Disposition": "inline; filename=\"preview_Classic.pdf\"",
    "Cache-Control": "no-store",
    "body": "%PDF-1.4 ... (binario) ... %%EOF"
}
 

Example response (404, Sin comprobantes para preview):

{
    "success": false,
    "data": null,
    "message": "No hay comprobantes emitidos para generar un preview. Emita al menos un comprobante antes de usar preview.",
    "errors": null
}
 

Example response (404, Plantilla no encontrada):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Logo disponible):

{
    "Content-Type": "image/png",
    "Cache-Control": "private, max-age=3600",
    "X-Content-Type-Options": "nosniff",
    "body": "(contenido binario de la imagen)"
}
 

Example response (404, Plantilla sin logo configurado):

{
    "success": false,
    "data": null,
    "message": "Esta plantilla no tiene logo.",
    "errors": null
}
 

Example response (404, Archivo de logo no encontrado en el servidor):

{
    "success": false,
    "data": null,
    "message": "Archivo de logo no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "logo_file=@/tmp/php3okg9sr9ghif59DykAr" 

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('logo_file', document.querySelector('input[name="logo_file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'logo_file',
                'contents' => fopen('/tmp/php3okg9sr9ghif59DykAr', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Logo subido exitosamente):

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Classic",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {},
            "fonts": {},
            "layout": {},
            "qr": {}
        },
        "has_logo": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T12:00:00-06:00"
    },
    "message": "Logo subido correctamente.",
    "errors": null
}
 

Example response (422, Archivo faltante):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "El archivo del logo es obligatorio."
        ]
    }
}
 

Example response (422, Extensión no permitida):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "Extensión no permitida. Use: png, jpg, jpeg, svg."
        ]
    }
}
 

Example response (422, Archivo excede 200 KB):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "El logo no puede superar 200 KB."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Logo eliminado):

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Classic",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {},
            "fonts": {},
            "layout": {},
            "qr": {}
        },
        "has_logo": false,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T13:00:00-06:00"
    },
    "message": "Logo eliminado correctamente.",
    "errors": null
}
 

Example response (409, Sin logo configurado):

{
    "success": false,
    "data": null,
    "message": "Esta plantilla no tiene logo configurado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/email-settings" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/email-settings"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/email-settings';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Valores por defecto (nunca configurado)):

{
    "success": true,
    "data": {
        "auto_send": true,
        "send_on_accepted_only": true,
        "attach_xml": true,
        "attach_pdf": true,
        "reply_to": null,
        "bcc": [],
        "custom_subject": null,
        "custom_message": null
    },
    "message": "Configuración de email del contribuyente.",
    "errors": null
}
 

Example response (200, Configuración personalizada):

{
    "success": true,
    "data": {
        "auto_send": true,
        "send_on_accepted_only": true,
        "attach_xml": true,
        "attach_pdf": true,
        "reply_to": "facturas@miempresa.cr",
        "bcc": [
            "contabilidad@miempresa.cr"
        ],
        "custom_subject": "{emisor} — {tipo} {consecutivo}",
        "custom_message": "Adjunto su comprobante electrónico."
    },
    "message": "Configuración de email del contribuyente.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/email-settings" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"auto_send\": true,
    \"send_on_accepted_only\": true,
    \"attach_xml\": true,
    \"attach_pdf\": true,
    \"reply_to\": \"facturas@miempresa.cr\",
    \"bcc\": [
        \"b\"
    ],
    \"custom_subject\": \"{emisor} — {tipo} {consecutivo}\",
    \"custom_message\": \"Adjunto encontrará su comprobante electrónico.\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/email-settings"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "auto_send": true,
    "send_on_accepted_only": true,
    "attach_xml": true,
    "attach_pdf": true,
    "reply_to": "facturas@miempresa.cr",
    "bcc": [
        "b"
    ],
    "custom_subject": "{emisor} — {tipo} {consecutivo}",
    "custom_message": "Adjunto encontrará su comprobante electrónico."
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/email-settings';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'auto_send' => true,
            'send_on_accepted_only' => true,
            'attach_xml' => true,
            'attach_pdf' => true,
            'reply_to' => 'facturas@miempresa.cr',
            'bcc' => [
                'b',
            ],
            'custom_subject' => '{emisor} — {tipo} {consecutivo}',
            'custom_message' => 'Adjunto encontrará su comprobante electrónico.',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Configuración actualizada):

{
    "success": true,
    "data": {
        "auto_send": true,
        "send_on_accepted_only": true,
        "attach_xml": true,
        "attach_pdf": true,
        "reply_to": "facturas@miempresa.cr",
        "bcc": [
            "contabilidad@miempresa.cr"
        ],
        "custom_subject": "{emisor} — {tipo} {consecutivo}",
        "custom_message": "Adjunto su comprobante electrónico."
    },
    "message": "Configuración de email actualizada correctamente.",
    "errors": null
}
 

Example response (422, Error de validación):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "reply_to": [
            "El campo reply_to debe ser un correo electrónico válido."
        ],
        "bcc.0": [
            "El campo bcc.0 debe ser un correo electrónico válido."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/clients?q=Empresa&id_type=02&is_active=true&per_page=15&page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/clients"
);

const params = {
    "q": "Empresa",
    "id_type": "02",
    "is_active": "true",
    "per_page": "15",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/clients';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'q' => 'Empresa',
            'id_type' => '02',
            'is_active' => 'true',
            'per_page' => '15',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listado paginado):

{
    "success": true,
    "data": [
        {
            "id": "019d867d-0001-7288-8ece-fd64da756001",
            "id_type": "02",
            "id_type_label": "Cédula Jurídica",
            "id_number": "3101123456",
            "name": "EMPRESA EJEMPLO S.A.",
            "commercial_name": "Ejemplo Shop",
            "location": {
                "province": 1,
                "canton": "01",
                "district": "01"
            },
            "neighborhood": "San Pedro",
            "address": "200 metros norte del parque central",
            "phone": {
                "country_code": 506,
                "number": "22001234"
            },
            "emails": [
                "facturacion@ejemplo.cr"
            ],
            "default_activity_code": "6121.0",
            "notes": "Cliente preferencial",
            "is_active": true,
            "has_location": true,
            "has_email": true,
            "created_at": "2026-04-01T10:00:00-06:00",
            "updated_at": "2026-04-10T14:30:00-06:00"
        }
    ],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 4,
        "per_page": 15,
        "total": 50,
        "from": 1,
        "to": 15
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    }
}
 

Example response (200, Sin resultados):

{
    "success": true,
    "data": [],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 0,
        "from": null,
        "to": null
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": null
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/clients" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"id_type\": \"02\",
    \"id_number\": \"3101123456\",
    \"name\": \"EMPRESA EJEMPLO S.A.\",
    \"commercial_name\": \"Ejemplo Shop\",
    \"province\": 1,
    \"canton\": 1,
    \"district\": 1,
    \"neighborhood\": \"San Pedro\",
    \"address\": \"200 metros norte del parque central\",
    \"phone_country_code\": 506,
    \"phone\": \"22001234\",
    \"emails\": [
        \"facturacion@ejemplo.cr\"
    ],
    \"default_activity_code\": \"6121.0\",
    \"notes\": \"Cliente preferencial\",
    \"is_active\": true
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/clients"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "id_type": "02",
    "id_number": "3101123456",
    "name": "EMPRESA EJEMPLO S.A.",
    "commercial_name": "Ejemplo Shop",
    "province": 1,
    "canton": 1,
    "district": 1,
    "neighborhood": "San Pedro",
    "address": "200 metros norte del parque central",
    "phone_country_code": 506,
    "phone": "22001234",
    "emails": [
        "facturacion@ejemplo.cr"
    ],
    "default_activity_code": "6121.0",
    "notes": "Cliente preferencial",
    "is_active": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/clients';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'id_type' => '02',
            'id_number' => '3101123456',
            'name' => 'EMPRESA EJEMPLO S.A.',
            'commercial_name' => 'Ejemplo Shop',
            'province' => 1,
            'canton' => 1,
            'district' => 1,
            'neighborhood' => 'San Pedro',
            'address' => '200 metros norte del parque central',
            'phone_country_code' => 506,
            'phone' => '22001234',
            'emails' => [
                'facturacion@ejemplo.cr',
            ],
            'default_activity_code' => '6121.0',
            'notes' => 'Cliente preferencial',
            'is_active' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Cliente creado):

{
    "success": true,
    "data": {
        "id": "019d867d-0002-7288-8ece-fd64da756002",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101123456",
        "name": "EMPRESA EJEMPLO S.A.",
        "commercial_name": "Ejemplo Shop",
        "location": {
            "province": 1,
            "canton": "01",
            "district": "01"
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "emails": [
            "facturacion@ejemplo.cr"
        ],
        "default_activity_code": "6121.0",
        "notes": "Cliente preferencial",
        "is_active": true,
        "has_location": true,
        "has_email": true,
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Cliente creado correctamente.",
    "errors": null
}
 

Example response (422, Identificación duplicada):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "id_number": [
            "Ya existe un cliente con este tipo y número de identificación."
        ]
    }
}
 

Example response (422, Formato de actividad económica inválido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "default_activity_code": [
            "Debe tener el formato XXXX.X (ejemplo: 6121.0)."
        ]
    }
}
 

Example response (422, Tipo de identificación inválido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "id_type": [
            "El tipo seleccionado no es válido."
        ]
    }
}
 

Example response (422, Límite del plan alcanzado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "plan": [
            "Ha alcanzado el límite de clientes de su plan. Actualice a un plan superior."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Cliente encontrado):

{
    "success": true,
    "data": {
        "id": "019d867d-0001-7288-8ece-fd64da756001",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101123456",
        "name": "EMPRESA EJEMPLO S.A.",
        "commercial_name": "Ejemplo Shop",
        "location": {
            "province": 1,
            "canton": "01",
            "district": "01"
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "emails": [
            "facturacion@ejemplo.cr"
        ],
        "default_activity_code": "6121.0",
        "notes": "Cliente preferencial",
        "is_active": true,
        "has_location": true,
        "has_email": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-10T14:30:00-06:00"
    },
    "message": "",
    "errors": null
}
 

Example response (404, No encontrado):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"id_type\": \"02\",
    \"id_number\": \"3101123456\",
    \"name\": \"Nombre Actualizado S.A.\",
    \"commercial_name\": \"Nuevo Nombre Comercial\",
    \"province\": 1,
    \"canton\": 1,
    \"district\": 1,
    \"neighborhood\": \"Escalante\",
    \"address\": \"Frente al parque\",
    \"phone_country_code\": 506,
    \"phone\": \"22009999\",
    \"emails\": [
        \"facturacion@ejemplo.cr\",
        \"contabilidad@ejemplo.cr\"
    ],
    \"default_activity_code\": \"6121.0\",
    \"notes\": \"Cliente preferencial — actualizado\",
    \"is_active\": true
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "id_type": "02",
    "id_number": "3101123456",
    "name": "Nombre Actualizado S.A.",
    "commercial_name": "Nuevo Nombre Comercial",
    "province": 1,
    "canton": 1,
    "district": 1,
    "neighborhood": "Escalante",
    "address": "Frente al parque",
    "phone_country_code": 506,
    "phone": "22009999",
    "emails": [
        "facturacion@ejemplo.cr",
        "contabilidad@ejemplo.cr"
    ],
    "default_activity_code": "6121.0",
    "notes": "Cliente preferencial — actualizado",
    "is_active": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'id_type' => '02',
            'id_number' => '3101123456',
            'name' => 'Nombre Actualizado S.A.',
            'commercial_name' => 'Nuevo Nombre Comercial',
            'province' => 1,
            'canton' => 1,
            'district' => 1,
            'neighborhood' => 'Escalante',
            'address' => 'Frente al parque',
            'phone_country_code' => 506,
            'phone' => '22009999',
            'emails' => [
                'facturacion@ejemplo.cr',
                'contabilidad@ejemplo.cr',
            ],
            'default_activity_code' => '6121.0',
            'notes' => 'Cliente preferencial — actualizado',
            'is_active' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Cliente actualizado):

{
    "success": true,
    "data": {
        "id": "019d867d-0001-7288-8ece-fd64da756001",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101123456",
        "name": "Nombre Actualizado S.A.",
        "commercial_name": "Nuevo Nombre Comercial",
        "location": {
            "province": 1,
            "canton": "01",
            "district": "01"
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "emails": [
            "facturacion@ejemplo.cr",
            "contabilidad@ejemplo.cr"
        ],
        "default_activity_code": "6121.0",
        "notes": "Cliente preferencial — actualizado",
        "is_active": true,
        "has_location": true,
        "has_email": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T11:00:00-06:00"
    },
    "message": "Cliente actualizado correctamente.",
    "errors": null
}
 

Example response (404, Cliente no encontrado):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Example response (422, Identificación duplicada):

{
    "success": false,
    "data": null,
    "message": "Ya existe un cliente con este tipo y número de identificación.",
    "errors": {
        "id_number": [
            "Duplicado para este contribuyente."
        ]
    }
}
 

Example response (422, Formato de actividad económica inválido):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "default_activity_code": [
            "Debe tener el formato XXXX.X (ejemplo: 6121.0)."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/clients/019d867d-0001-7288-8ece-fd64da756001';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Cliente eliminado):

{
    "success": true,
    "data": null,
    "message": "Cliente eliminado correctamente.",
    "errors": null
}
 

Example response (404, No encontrado):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/items?q=consultor%C3%ADa&cabys_code=4233201000000&is_active=true&per_page=15&page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/items"
);

const params = {
    "q": "consultoría",
    "cabys_code": "4233201000000",
    "is_active": "true",
    "per_page": "15",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/items';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'q' => 'consultoría',
            'cabys_code' => '4233201000000',
            'is_active' => 'true',
            'per_page' => '15',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Listado paginado):

{
    "success": true,
    "data": [
        {
            "id": "019d867d-0010-7288-8ece-fd64da756010",
            "cabys_code": "4233201000000",
            "internal_code": "SKU-001",
            "description": "Servicio de consultoría profesional",
            "unit_of_measure": "Sp",
            "unit_of_measure_label": "Servicios Profesionales",
            "commercial_unit": null,
            "unit_price": "50000.00000",
            "tax": {
                "code": "01",
                "rate_code": "08",
                "rate": "13.00",
                "label": "IVA 13%"
            },
            "is_mercancia": false,
            "is_servicio": true,
            "is_active": true,
            "created_at": "2026-04-01T10:00:00-06:00",
            "updated_at": "2026-04-10T14:30:00-06:00"
        }
    ],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 2,
        "per_page": 15,
        "total": 30,
        "from": 1,
        "to": 15
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    }
}
 

Example response (200, Sin resultados):

{
    "success": true,
    "data": [],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 0,
        "from": null,
        "to": null
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": null
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/items" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"cabys_code\": \"4233201000000\",
    \"internal_code\": \"SKU-001\",
    \"description\": \"Servicio de consultoría profesional\",
    \"unit_of_measure\": \"Sp\",
    \"commercial_unit\": \"caja x 12\",
    \"unit_price\": 50000,
    \"tax_code\": \"01\",
    \"tax_rate_code\": \"08\",
    \"tax_rate\": 13,
    \"is_active\": true
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/items"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "cabys_code": "4233201000000",
    "internal_code": "SKU-001",
    "description": "Servicio de consultoría profesional",
    "unit_of_measure": "Sp",
    "commercial_unit": "caja x 12",
    "unit_price": 50000,
    "tax_code": "01",
    "tax_rate_code": "08",
    "tax_rate": 13,
    "is_active": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/items';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'cabys_code' => '4233201000000',
            'internal_code' => 'SKU-001',
            'description' => 'Servicio de consultoría profesional',
            'unit_of_measure' => 'Sp',
            'commercial_unit' => 'caja x 12',
            'unit_price' => 50000.0,
            'tax_code' => '01',
            'tax_rate_code' => '08',
            'tax_rate' => 13.0,
            'is_active' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201, Item creado):

{
    "success": true,
    "data": {
        "id": "019d867d-0011-7288-8ece-fd64da756011",
        "cabys_code": "4233201000000",
        "internal_code": "SKU-001",
        "description": "Servicio de consultoría profesional",
        "unit_of_measure": "Sp",
        "unit_of_measure_label": "Servicios Profesionales",
        "commercial_unit": null,
        "unit_price": "50000.00000",
        "tax": {
            "code": "01",
            "rate_code": "08",
            "rate": "13.00",
            "label": "IVA 13%"
        },
        "is_mercancia": false,
        "is_servicio": true,
        "is_active": true,
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Item creado correctamente.",
    "errors": null
}
 

Example response (422, Código interno duplicado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "internal_code": [
            "Ya existe un item con este código interno."
        ]
    }
}
 

Example response (422, Código CABYS no existe en el catálogo):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "cabys_code": [
            "El código CABYS no existe en el catálogo vigente."
        ]
    }
}
 

Example response (422, Falta tax_rate_code para IVA):

{
    "success": false,
    "data": null,
    "message": "tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA cálculo especial (07).",
    "errors": {
        "tax_rate_code": [
            "tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA cálculo especial (07)."
        ]
    }
}
 

Example response (422, Unit_of_measure 'Otros' sin commercial_unit):

{
    "success": false,
    "data": null,
    "message": "commercial_unit es obligatoria cuando unit_of_measure es 'Otros'.",
    "errors": {
        "commercial_unit": [
            "commercial_unit es obligatoria cuando unit_of_measure es 'Otros'."
        ]
    }
}
 

Example response (422, Límite del plan alcanzado):

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "plan": [
            "Ha alcanzado el límite de items de su plan. Actualice a un plan superior."
        ]
    }
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Item encontrado):

{
    "success": true,
    "data": {
        "id": "019d867d-0010-7288-8ece-fd64da756010",
        "cabys_code": "4233201000000",
        "internal_code": "SKU-001",
        "description": "Servicio de consultoría profesional",
        "unit_of_measure": "Sp",
        "unit_of_measure_label": "Servicios Profesionales",
        "commercial_unit": null,
        "unit_price": "50000.00000",
        "tax": {
            "code": "01",
            "rate_code": "08",
            "rate": "13.00",
            "label": "IVA 13%"
        },
        "is_mercancia": false,
        "is_servicio": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-10T14:30:00-06:00"
    },
    "message": "",
    "errors": null
}
 

Example response (404, No encontrado):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Received response:

Request failed with error:

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Example request:

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"cabys_code\": \"4233201000000\",
    \"internal_code\": \"SKU-001-V2\",
    \"description\": \"Servicio de consultoría profesional actualizado\",
    \"unit_of_measure\": \"Sp\",
    \"commercial_unit\": \"caja x 12\",
    \"unit_price\": 55000,
    \"tax_code\": \"01\",
    \"tax_rate_code\": \"08\",
    \"tax_rate\": 13,
    \"is_active\": true
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "cabys_code": "4233201000000",
    "internal_code": "SKU-001-V2",
    "description": "Servicio de consultoría profesional actualizado",
    "unit_of_measure": "Sp",
    "commercial_unit": "caja x 12",
    "unit_price": 55000,
    "tax_code": "01",
    "tax_rate_code": "08",
    "tax_rate": 13,
    "is_active": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/items/019d867d-0010-7288-8ece-fd64da756010';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'cabys_code' => '4233201000000',
            'internal_code' => 'SKU-001-V2',
            'description' => 'Servicio de consultoría profesional actualizado',
            'unit_of_measure' => 'Sp',
            'commercial_unit' => 'caja x 12',
            'unit_price' => 55000.0,
            'tax_code' => '01',
            'tax_rate_code' => '08',
            'tax_rate' => 13.0,
            'is_active' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, Item actualizado):

{
    "success": true,
    "data": {
        "id": "019d867d-0010-7288-8ece-fd64da756010",
        "cabys_code": "4233201000000",
        "internal_code": "SKU-001-V2",
        "description": "Servicio de consultoría profesional actualizado",
        "unit_of_measure": "Sp",
        "unit_of_measure_label": "Servicios Profesionales",
        "commercial_unit": null,
        "unit_price": "55000.00000",
        "tax": {
            "code": "01",
            "rate_code": "08",
            "rate": "13.00",
            "label": "IVA 13%"
        },
        "is_mercancia": false,
        "is_servicio": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T11:00:00-06:00"
    },
    "message": "Item actualizado correctamente.",
    "errors": null
}
 

Example response (404, Item no encontrado):

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Example response (422, Código interno duplicado):

{
    "success": false,
    "data": null,
    "message": "Ya existe un item con el código interno [SKU-001-V2].",
    "errors": {
        "internal_code": [
            "Duplicado para este contribuyente."
        ]
    }
}
 

Example response (422, Código CABYS no existe):

{
    "success": false,
    "data": null,
    "message": "El código CABYS [9999999999999] no existe en el catálogo vigente.",
    "errors": {
        "cabys_code": [
            "Código CABYS no encontrado."
        ]
    }
}
 

Example response (422, Falta tax_rate_code para IVA):

{
    "success": false,
    "data": null,
    "message": "tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA cálculo especial (07).",
    "errors": {
        "tax_rate_code": [
            "tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA cálculo especial (07)."
        ]
    }
}