cURL examples

#!/usr/bin/env bash
# Your first call: extract the hosted sample certificate (fictitious data).
# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.
set -euo pipefail

REQUEST_ID="first-call-$(date +%s)-$RANDOM" # one id per document

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "$REQUEST_ID"
}
EOF

#!/usr/bin/env bash
# Extract a certificate from a local file, sent in base64. The JSON body is
# written to a file, so a large image never becomes a shell argument.
# Needs DOCSOCR_API_KEY in the environment.
set -euo pipefail

FILE="certificate.jpg"
REQUEST_ID="local-file-$(date +%s)-$RANDOM" # one id per document

{
  printf '{"imageType":"base64","requestId":"%s","imageBase64":"' "$REQUEST_ID"
  base64 < "$FILE" | tr -d '\n'
  printf '"}'
} > body.json

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

#!/usr/bin/env bash
# Extract an image outside our standard: resizeImage brings it to the
# standard first, for one extra credit (the 800x640 sample is too small).
# Needs DOCSOCR_API_KEY in the environment.
set -euo pipefail

REQUEST_ID="resize-$(date +%s)-$RANDOM" # one id per document

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg",
  "requestId": "$REQUEST_ID",
  "resizeImage": true
}
EOF

#!/usr/bin/env bash
# Ask for the fast engine: it is tried first, at its own price, and the
# standard engines follow when it cannot answer. The answer names the engine
# that answered and what it cost. Needs DOCSOCR_API_KEY in the environment.
set -euo pipefail

REQUEST_ID="fast-$(date +%s)-$RANDOM" # one id per document

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "$REQUEST_ID",
  "engine": "fast"
}
EOF

#!/usr/bin/env bash
# Extract a certificate, handling every answer, with retries that never charge twice.
# Each retry sends the same requestId: a repeat of a finished request gets its
# kept answer at no charge, and a repeat of one still running is told to wait (409).
# Needs DOCSOCR_API_KEY in the environment.
set -uo pipefail

REQUEST_ID="errors-$(date +%s)-$RANDOM" # one id per document, the same on every retry
BODY="{\"imageType\":\"url\",\"imageUrl\":\"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\"requestId\":\"$REQUEST_ID\"}"

for attempt in 0 1 2 3 4; do
  backoff=$((1 << attempt)) # seconds: 1, 2, 4, 8
  # Above the API's 90 s extraction budget; a timeout or a dropped connection is retried
  if ! status=$(curl -sS --max-time 120 -o answer.json -w '%{http_code}' \
    https://api.docsocr.com/api/v1/documents/birth-certificate \
    -H "Authorization: Bearer $DOCSOCR_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary "$BODY"); then
    sleep "$backoff"
    continue
  fi
  if [ "$status" = 201 ] && grep -q '"success":true' answer.json; then
    cat answer.json
    exit 0
  fi
  error_code=$(grep -o '"errorCode":"[A-Z_]*"' answer.json | cut -d'"' -f4)
  # Wait as long as the answer asks (retryAfter); a limit that resets
  # later, such as a daily quota, is not worth waiting for
  wait=$(grep -o '"retryAfter":[0-9]*' answer.json | cut -d: -f2)
  wait=${wait:-$backoff}
  case "$status:$error_code" in
    # No engine could answer (nothing was charged); still in progress;
    # too many requests; the service restarting
    201:EXTRACTION_BUSY | 201:EXTRACTION_TIMEOUT | 201:EXTRACTION_UNAVAILABLE | 409:* | 429:* | 502:* | 503:* | 504:*)
      if [ "$wait" -le 60 ]; then
        sleep "$wait"
        continue
      fi
      ;;
  esac
  # 400 the body, 401 the key, 402 NOT_ENOUGH_CREDITS, 422 the image
  # (its errorCode says what to fix), DOCUMENT_NOT_RECOGNIZED: fix it, don't retry
  echo "$status $error_code $(cat answer.json)" >&2
  exit 1
done
echo "No answer after retries: try again later" >&2
exit 1

#!/usr/bin/env bash
# The price of an extraction, in credits, per engine and for resizeImage.
# A public endpoint: no key needed.
set -euo pipefail

curl -sS --max-time 30 https://api.docsocr.com/api/v1/documents/prices