Integrazio-gida

Probatu APIa demo-token batekin

sk_demo_ token bat eska dezakezu konturik edo erakunderik erregistratu gabe. Jaulkitzen denetik 24 ordu irauten du eta eskatu duen IP publikotik bakarrik funtzionatzen du. Sarea edo IPa aldatuz gero, beste token bat eskatu behar da.

Erabili fikziozko datuak soilik. PDFaren orrialde guztietan BALIORIK GABE agertzen da logoaren ondoan, eta DEMO marka diagonal bat ere bai. Dokumentu hauek ez dute balio salgaiak garraiatzeko edo baliozko administrazio-dokumentu gisa erabiltzeko.

1. Eskatu tokena

Bidali JSON objektu huts bat endpoint publiko honetara. Ez du Bearer goibururik behar. 201 erantzunak token eta expires_at ditu; iraungitze-data UTCn adierazten da.

Tokena eskatzean document_locale bidal dezakezu: es, ca, gl, ca-valencia, eu, en, pt-pt edo fr. Adibidez, {"document_locale":"en"} bidaliz PDFak ingelesez sortzen dira. Eremurik gabe es erabiltzen da. Erantzunak aukeratutako hizkuntza dakar; aldatzeko, eskatu token berri bat.

Kodea
curl 'https://deca.sertecpesage.com/api/v1/demo/tokens' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{}'

Kodea
{
  "token": "sk_demo_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "expires_at": "2026-10-07T11:00:00Z",
  "document_locale": "es"
}

2. Jaulki adibideko dokumentu bat

Gorde JSON hau document.json izenarekin. Demoak ohiko kontratuaren bide eta eremu berak erabiltzen ditu eta garraio-datuak baliozkotzen ditu. Adibideko izenak, helbideak eta erreferentziak fikziozkoak dira.

Kodea
{
  "reference": "DEMO-001",
  "transport_date": "2026-10-06",
  "shipper": {
    "name": "Empresa de ejemplo, S. L.",
    "tax_country": "ES",
    "tax_id": "B12345674",
    "address": {
      "street": "Calle de Ejemplo, 1",
      "postal_code": "08040",
      "city": "Barcelona",
      "country": "ES"
    }
  },
  "carrier": {
    "name": "Transportes de ejemplo, S. L.",
    "tax_country": "ES",
    "tax_id": "B87654323"
  },
  "origin": {
    "place": "Almacén de ejemplo",
    "city": "Barcelona",
    "country": "ES"
  },
  "destination": {
    "place": "Centro de ejemplo",
    "city": "Zaragoza",
    "country": "ES"
  },
  "goods": {
    "description": "Mercancía de demostración",
    "weight_kg": "1850.000"
  },
  "vehicle": {
    "country": "ES",
    "registration": "4827 MNL"
  },
  "metadata": {
    "example": true
  }
}

Bidali eskaera IP beretik eta ordeztu YOUR_DEMO_TOKEN jasotako tokenarekin:

Kodea
curl 'https://deca.sertecpesage.com/api/v1/documents' \
  --request POST \
  --header 'Authorization: Bearer YOUR_DEMO_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data @document.json

Erantzunak uuid, url, qr, pdf_download_url, normalized_data, metadata, rectifies_uuid eta document_locale ditu, ohiko APIak bezala. Demoak expires_at, qr_url eta pdf_url gehitzen ditu. Gorde UUIDa eta erabili jasotako URLak.

Demoak demo: true ere itzultzen du; PDFak tokena eskatzean aukeratutako document_locale erabiltzen du, es lehenespenez. qr_url url-ren aliasa da eta pdf_url pdf_download_url-rena.

3. Kontsultatu eta ireki PDFa

Dokumentuak zerrendatu, kontsultatu, zuzendu eta ezaba ditzakezu APIaren erreferentziako eragiketen bidez. Bearer deiek token eta IP bera eskatzen dute. Dokumentua kontsultatzeko:

Kodea
curl 'https://deca.sertecpesage.com/api/v1/documents/DOCUMENT_UUID' \
  --header 'Authorization: Bearer YOUR_DEMO_TOKEN' \
  --header 'Accept: application/json'

QRak PDFa zuzenean irekitzen du nabigatzailean /demo/d/{uuid}?k=... bidez, Bearerrik gabe. Dokumentua eta haren estekak demo-saioarekin batera iraungitzen dira; dokumentua sortzeak edo zuzentzeak ez du tokenaren iraupena luzatzen.

Iraungitako edo beste IP batetik bidalitako demo-tokenak 401 itzultzen du. Iraungitako demo-QRak 404 itzultzen du. Demoa desgaituta badago, 503 DEMO_UNAVAILABLE itzultzen du. QRrako lehen sarbideak edo zuzenketa batek dokumentua ezabatzea eragozten dute; ohiko kontratuaren ezabatze-baieztapenak mantentzen dira.

Iraungitzea, mugak eta pribatutasuna

Demoak aldi baterako biltegiratze bereizia du, benetako erabiltzaile, erakunde eta dokumentuetatik aparte. Haren datuek eta PDFek ez dituzte benetako artxiboaren zifratze-bermeak edo kontserbazio-epeak. Ez bidali datu pertsonalik, sekreturik edo benetako garraioen dokumenturik.

Tokena, haren dokumentuak eta estekak tokena jaulki eta 24 ordura iraungitzen dira; biltegiratze aktiboa aldizka garbitzen da. Hostingerren azken zazpi egunetako babeskopiek eta ezabatu aurretik egindako eskuzko kopiek demo-datuak gorde ditzakete kopia horiek kendu arte. Iraungitzeak ez du kopia guztien atzeraezinezko ezabaketa esan nahi.

Demoak gehienez 32 KiB-ko gorputzak eta saioko hamar dokumentu onartzen ditu. IP beretik minutuko hiru eta orduko hamar token jaulki daitezke; dokumentuak sortzeko, minutuko bost eta orduko hogei. Sarearen, eskualdearen eta karga globalaren muga partekatuak lehenago aplika daitezke. Kopuru hauek konfigurazio lehenetsiari dagozkio.

Gehiegizko erabilera saihesteko, token-jaulkipenek, eskaerek, dokumentuek eta deskargek mugak dituzte. IParen, sarearen, eskualdearen eta karga globalaren araberako kontrolak ere badaude; muga partekatuek eskaera eragotz dezakete zure tokenak bere mugara iritsi ez arren. 429 jasoz gero, itxaron Retry-After goiburuan adierazitako segundoak.

Eskualdearen araberako kontrolak ez du IP-geolokalizazioko zerbitzurik erabiltzen. CF-IPCountry soilik erabiltzen da eskaera DEMO_TRUSTED_GEO_PROXIES zerrendako proxy egiaztatu batetik iristen denean; proxyak Cloudflare-ren goiburuak gainidatzi behar ditu. Beste jatorri batzuetatik, goiburu horiek ez dira kontuan hartzen eta eskaera guztiek unverified eskualde-taldea partekatzen dute; ez zaie egiaztatutako herrialderik esleitzen.

Babestu tokena eta esteketako k sekretua; ez argitaratu eta ez sartu erregistroetan. Integrazio iraunkor bat egiteko, eskatu sarbidea SERTEC PESAGEri. sk_test_ eta sk_live_ inguruneek beren arau eta datuak mantentzen dituzte.